<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.4.5" />
<title>TMQL4J Documentation and Tutorials</title>
<style type="text/css">
/* Debug borders */
p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
/*
  border: 1px solid red;
*/
}

body {
  margin: 1em 5% 1em 5%;
}

a {
  color: blue;
  text-decoration: underline;
}
a:visited {
  color: fuchsia;
}

em {
  font-style: italic;
  color: navy;
}

strong {
  font-weight: bold;
  color: #083194;
}

tt {
  color: navy;
}

h1, h2, h3, h4, h5, h6 {
  color: #527bbd;
  font-family: sans-serif;
  margin-top: 1.2em;
  margin-bottom: 0.5em;
  line-height: 1.3;
}

h1, h2, h3 {
  border-bottom: 2px solid silver;
}
h2 {
  padding-top: 0.5em;
}
h3 {
  float: left;
}
h3 + * {
  clear: left;
}

div.sectionbody {
  font-family: serif;
  margin-left: 0;
}

hr {
  border: 1px solid silver;
}

p {
  margin-top: 0.5em;
  margin-bottom: 0.5em;
}

ul, ol, li > p {
  margin-top: 0;
}

pre {
  padding: 0;
  margin: 0;
}

span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
}
span#email {
}
span#revnumber, span#revdate, span#revremark {
  font-family: sans-serif;
}

div#footer {
  font-family: sans-serif;
  font-size: small;
  border-top: 2px solid silver;
  padding-top: 0.5em;
  margin-top: 4.0em;
}
div#footer-text {
  float: left;
  padding-bottom: 0.5em;
}
div#footer-badges {
  float: right;
  padding-bottom: 0.5em;
}

div#preamble {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
div.admonitionblock {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
}
div.admonitionblock {
  margin-top: 2.5em;
  margin-bottom: 2.5em;
}

div.content { /* Block element content. */
  padding: 0;
}

/* Block element titles. */
div.title, caption.title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  text-align: left;
  margin-top: 1.0em;
  margin-bottom: 0.5em;
}
div.title + * {
  margin-top: 0;
}

td div.title:first-child {
  margin-top: 0.0em;
}
div.content div.title:first-child {
  margin-top: 0.0em;
}
div.content + div.title {
  margin-top: 0.0em;
}

div.sidebarblock > div.content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}

div.listingblock > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock {
  padding-left: 2.0em;
  margin-right: 10%;
}
div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock {
  padding-left: 2.0em;
  margin-right: 10%;
}
div.verseblock > div.content {
  white-space: pre;
}
div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
}
/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
div.verseblock + div.attribution {
  text-align: left;
}

div.admonitionblock .icon {
  vertical-align: top;
  font-size: 1.1em;
  font-weight: bold;
  text-decoration: underline;
  color: #527bbd;
  padding-right: 0.5em;
}
div.admonitionblock td.content {
  padding-left: 0.5em;
  border-left: 2px solid silver;
}

div.exampleblock > div.content {
  border-left: 2px solid silver;
  padding: 0.5em;
}

div.imageblock div.content { padding-left: 0; }
span.image img { border-style: none; }
a.image:visited { color: white; }

dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
}
dd > *:first-child {
  margin-top: 0.1em;
}

ul, ol {
    list-style-position: outside;
}
ol.arabic {
  list-style-type: decimal;
}
ol.loweralpha {
  list-style-type: lower-alpha;
}
ol.upperalpha {
  list-style-type: upper-alpha;
}
ol.lowerroman {
  list-style-type: lower-roman;
}
ol.upperroman {
  list-style-type: upper-roman;
}

div.compact ul, div.compact ol,
div.compact p, div.compact p,
div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
}

div.tableblock > table {
  border: 3px solid #527bbd;
}
thead {
  font-family: sans-serif;
  font-weight: bold;
}
tfoot {
  font-weight: bold;
}
td > div.verse {
  white-space: pre;
}
p.table {
  margin-top: 0;
}
/* Because the table frame attribute is overriden by CSS in most browsers. */
div.tableblock > table[frame="void"] {
  border-style: none;
}
div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
}
div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
}


div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
}
div.hdlist tr {
  padding-bottom: 15px;
}
dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
}
td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
}
td.hdlist2 {
  vertical-align: top;
}
div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
}

.comment {
  background: yellow;
}

@media print {
  div#footer-badges { display: none; }
}

div#toctitle {
  color: #527bbd;
  font-family: sans-serif;
  font-size: 1.1em;
  font-weight: bold;
  margin-top: 1.0em;
  margin-bottom: 0.1em;
}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
  margin-top: 0;
  margin-bottom: 0;
}
div.toclevel2 {
  margin-left: 2em;
  font-size: 0.9em;
}
div.toclevel3 {
  margin-left: 4em;
  font-size: 0.9em;
}
div.toclevel4 {
  margin-left: 6em;
  font-size: 0.9em;
}
/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {
  background: #ffffee;
  border: 1px solid silver;
  padding: 0.5em;
}
div.sidebar-title, div.image-title {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  margin-top: 0.0em;
  margin-bottom: 0.5em;
}

div.listingblock div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
}

div.quoteblock-attribution {
  padding-top: 0.5em;
  text-align: right;
}

div.verseblock-content {
  white-space: pre;
}
div.verseblock-attribution {
  padding-top: 0.75em;
  text-align: left;
}

div.exampleblock-content {
  border-left: 2px solid silver;
  padding-left: 0.5em;
}

/* IE6 sets dynamically generated links as visited. */
div#toc a:visited { color: blue; }
</style>
<script type="text/javascript">
/*<![CDATA[*/
window.onload = function(){generateToc(2)}
/* Author: Mihai Bazon, September 2002
 * http://students.infoiasi.ro/~mishoo
 *
 * Table Of Content generator
 * Version: 0.4
 *
 * Feel free to use this script under the terms of the GNU General Public
 * License, as long as you do not remove or alter this notice.
 */

 /* modified by Troy D. Hanson, September 2006. License: GPL */
 /* modified by Stuart Rackham, October 2006. License: GPL */

function getText(el) {
  var text = "";
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
    if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
      text += i.data;
    else if (i.firstChild != null)
      text += getText(i);
  }
  return text;
}

function TocEntry(el, text, toclevel) {
  this.element = el;
  this.text = text;
  this.toclevel = toclevel;
}

function tocEntries(el, toclevels) {
  var result = new Array;
  var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
  // Function that scans the DOM tree for header elements (the DOM2
  // nodeIterator API would be a better technique but not supported by all
  // browsers).
  var iterate = function (el) {
    for (var i = el.firstChild; i != null; i = i.nextSibling) {
      if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
        var mo = re.exec(i.tagName)
        if (mo)
          result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
        iterate(i);
      }
    }
  }
  iterate(el);
  return result;
}

// This function does the work. toclevels = 1..4.
function generateToc(toclevels) {
  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
  for (var i = 0; i < entries.length; ++i) {
    var entry = entries[i];
    if (entry.element.id == "")
      entry.element.id = "toc" + i;
    var a = document.createElement("a");
    a.href = "#" + entry.element.id;
    a.appendChild(document.createTextNode(entry.text));
    var div = document.createElement("div");
    div.appendChild(a);
    div.className = "toclevel" + entry.toclevel;
    toc.appendChild(div);
  }
  if (entries.length == 0)
    document.getElementById("header").removeChild(toc);
}
/*]]>*/
</script>
</head>
<body>
<div id="header">
<h1>TMQL4J Documentation and Tutorials</h1>
<div id="toc">
  <div id="toctitle">Table of Contents</div>
  <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
</div>
</div>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph"><p>TMQL4J is an open source project available under an Apache 2.0 license. The project is hosted on <a href="http://code.google.com/p/tmql/">http://code.google.com/p/tmql/</a>. If you find bugs or have feature requests please file a <a href="http://code.google.com/p/tmql/issues/list">ticket</a>.</p></div>
</div>
</div>
<h2 id="_scope_of_this_document">1. Scope of this document</h2>
<div class="sectionbody">
<div class="paragraph"><p>The Topic Maps Query Language is the name of a language specified for querying topic maps in an easy and consistent way independent of the underlying topic maps engine implementation. The query language is inspired by different languages which are established in different sectors of the technology infrastructures and models, like SQL or the topic maps query language TOLOG. Currently there is no final standard specification for TMQL but we decided to implement a topic maps query engine based on the draft of august 15th 2008 except any extension developed by the topic maps lab.</p></div>
<div class="paragraph"><p>The document is divided in three semantic sections.</p></div>
<div class="paragraph"><p>The first section describing the language specified in the underlying draft and the extensions. The section tries to give the user an overview about the query language itself and give the possibility to use the engine by creating the queries to extract the informations the user is interested in. The language part starts with the grammar description and continues with the base navigation and graph concept of TMQL, finishing with the complex high-level query languages.</p></div>
<div class="paragraph"><p>The second section describing the engine itself and give the user an short overview about the architecture and the plugin available for tmql4j. We describe how to use the engine, and how the user can extend or adapt the engine to realize the business use cases in the most comfortable way by using our core engine.</p></div>
<div class="paragraph"><p>The last section contains some tutorials to combine the knowledge gain in the both other sections of this document by realizing some base use cases, starting by a simple one and finishing in a complex use case.</p></div>
</div>
<h2 id="_topic_maps_query_language">2. Topic Maps Query Language</h2>
<div class="sectionbody">
<div class="paragraph"><p>Describing the query language.</p></div>
<h3 id="_the_meta_model_of_tmql">2.1. The meta model of TMQL</h3><div style="clear:left"></div>
<div class="paragraph"><p>The meta or data model of TMQL is quite different than the meta model of the topic maps ( TMDM ). There are many differences which are useful and show the different meanings and the huge discussion about the topic maps meta model. Currently the meta model of the query language includes concepts of the topic map reference model ( TMRM ) like the navigation concept which looks similar to the proxy concept of the reference model. Other import inputs are discussions about some changes of the topic maps meta model. As editors of the current draft some changes in context of the TMDM affected the current draft of the query language.</p></div>
<div class="paragraph"><p>This chapter tries to highlight the main differences between both conceptions the TMQL meta model on the one hand and the TMDM on the other hand.</p></div>
<h4 id="_no_topic_map_construct">2.1.1. No topic map construct</h4>
<div class="paragraph"><p>In contrast to the topic maps meta model the topic map construct can not be accessed directly. So it is impossible to get all topics or all associations by starting a navigation at the <em>root</em> node. If we look at the topic map API ( TMAPI ) the <em>root</em> node seems to be the topic map construct. As two main methods the topic map provides access to all topics and all associations. The TMAPI is currently based on the TMDM conception.</p></div>
<div class="paragraph"><p>The main problem of this drawback is the missing possiblity to get this information quite simple like it is supported by the TMAPI.</p></div>
<div class="paragraph"><p>The concept of missing the direct addressing of the topic maps item is similar to the concept of the CTM syntax. A topic map will never be addressed directly using a CTM pattern, it will be represented indirectly as the whole document. In this case TMQL addresses the topic map item indirectly as the querying context. There is only one possibility to use the topic maps item in the context of a query, the environment variable <em>%_</em> representing the queried topic map. But there is no possiblity to use it as a startingpoint for navigation.</p></div>
<h4 id="_only_one_item_identifier">2.1.2. Only one item-identifier</h4>
<div class="paragraph"><p>As a fundamental part of the current version of the TMDM everything is a topic map construct including names, occurrence, topics, associations, roles and the topic map itself. The TMDM construct can be identified by a number of item-identifiers except topic items, because they are identified by subject-identifiers and locators too. In this relation a topic map construct can have more than one item-identifier.</p></div>
<div class="paragraph"><p>To get access to the item-identifiers of a construct the query language supports a navigation axis called <em>item</em>. The navigation axis returns only one item-identifier, which means that a construct in the concept of the meta model of the query language can only have one item-identifier and not a set of them. If a construct has more than one, one is returned randomly</p></div>
<h4 id="_no_variants">2.1.3. No variants</h4>
<div class="paragraph"><p>In the concept of the topic maps meta model, a name item can contain a number of variants which represent a variation of this name in different datatypes like an audio-file or another spelling.</p></div>
<div class="paragraph"><p>In TMQL there is no axis supporting variants. It seems to be impossible to get variants of name items. In this case variants are removed from the meta model of the query language. The only way to access variants is to use the function <em>has-variant</em> which returns a set of all variants of a name item. The main problem is the fact, that variants can not be used as navigation nodes, so it is impossible to get the reifier or the scope of variants.</p></div>
<h4 id="_merging_the_concept_of_names_and_occurrences">2.1.4. Merging the concept of names and occurrences</h4>
<div class="paragraph"><p>The topic maps meta model differs the two concepts of names and occurrences. Names are used as human readable identification of topic items. A name item represents a name of a subject of the real world and will be represented as a string literal. Occurrences represent the relationship of subjects and an information resource. An occurrence can be used to bind a characteristic information resource to the topic item including the occurrence, for example its email address or its date of birth.</p></div>
<div class="paragraph"><p>In the context of information modelling the differences of names and occurrences are quite simple. Names can have variants and are always represented as a string literal which means names always have the datatype <em>string</em>. Occurrences have no variants and can have different datatypes, but also the datatype <em>string</em>. Because of removing variants from the meta model, names and occurrence are quite the same except the datatype because of the fact that occurrences can be a string literal too, this difference has no relevance. As a result of this discussion the current draft of the topic maps query language does not differs between names and occurrences. Both concepts are merged to the concept of <em>characteristics</em>. A characteristic item representing some relation of the topic item and an information resource which also can be a name, if the name type is used.</p></div>
<h4 id="_no_association_role_item">2.1.5. No association role item</h4>
<div class="paragraph"><p>The relation between topic items are modelled as an association item. The roles of associations are represented as special association role items, containing the role type, the role player and can be reified. This concept is defined by the topic maps meta model.</p></div>
<div class="paragraph"><p>In contrast to this concept the meta model of the query language does not contain a construct similar to the association role. The role as real construct can not materialized or queried. By using the navigation axis <em>roles</em> or <em>players</em> the role type or the role player can only accessed as topic item. The reification of roles lost.</p></div>
<h3 id="_language_grammar">2.2. Language grammar</h3><div style="clear:left"></div>
<div class="paragraph"><p>The grammar of the query language are modelled in three levels. Each level uses defined constructs of the lower level to extend them. In this context each grammar inspired by an industrial standard.</p></div>
<h4 id="_the_token_level">2.2.1. The token level</h4>
<div class="paragraph"><p>The token level creates the base of the query language by defining the terminal symbols. It makes use of regular expression to specify case-sensitive character patterns for valid terminal symbols. In the current draft TMQL contains constant tokens representing special keywords of the language itselfs like the keyword <em>SELECT</em>. In addition the draft contains terminal definitions using regular expressions, the terminal can be represented by different token literals, matching the given regular expression. For example variables have to start with a defined prefix <em>$</em> and have to contain at least one character after the prefix.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">Binary infix or unary prefix operators are not defined as a part of the grammar itself. They are handled as a part of the predefined environment in the same context as the functions representing the functionality of this operators. But these tokens are reserved too and can not be used in other meanings.</td>
</tr></table>
</div>
<div class="paragraph"><p>The token level defines a set of delimiting characters used to split special token representations automatically. Any other token is not delimiting and whitespace characters must be used for separation. Whitespace characters are blank, tabs and newlines and can be placed without quantified restrictions between every other token. The whitespaces wont be interpreted, except for their meaning in the context of string literals, XML fragments or CTM streams.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The hash character <em>#</em> is used for comments in the query context which wont be interpreted by the query processor. The hash character will be identified as a comment only if it is encapsulated by whitespaces and isn&#8217;t a part of a string literal.</td>
</tr></table>
</div>
<h4 id="_the_canonical_level">2.2.2. The canonical level</h4>
<div class="paragraph"><p>The definition of the canonical syntax is realized by using the context-free grammar of XML 1.0 with some additional conventions. The canonical level defines a set of productions for non-terminals representing the expressions of the query language. The productions make use of terminals of the token level and are represented as terms, a sequence of terminals and non-terminals.</p></div>
<h4 id="_the_non_canonical_level">2.2.3. The non-canonical level</h4>
<div class="paragraph"><p>The non-canonical level is realized on top of the canonical level and contains special term substituations to reduce the syntactic overhead of some expressions often used in this context of query syntax. The defined shortcuts are equal to its expanded forms and do not add any computational complexity.</p></div>
<h3 id="_literals_and_atoms">2.3. Literals and Atoms</h3><div style="clear:left"></div>
<div class="paragraph"><p>Literals are terminals which aren&#8217;t reserved keywords of the query language. Non-constant literals normally represent values of constant atoms like a string literal.</p></div>
<div class="paragraph"><p>Constant literals are called atoms and represent the internal datatypes which can be used in a constant way by using the identifier of the datatype. The current draft adopts a list of primitve datatypes of the CTM draft and add the <em>date</em> and <em>dateTime</em> datatype of XSD to define time as core types of the queried topic map. The following table contains a number of all predefined atoms and their values which can be represented by other literals.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="16%" />
<col width="83%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>datatype</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>possible values</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">atom</p></td>
<td align="left" valign="top"><p class="table">undefined | boolean | number | date | dateTime | iri | string  [  ^^  QIRI ]</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">undefined</p></td>
<td align="left" valign="top"><p class="table">undef</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">boolean</p></td>
<td align="left" valign="top"><p class="table">true | false</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">number</p></td>
<td align="left" valign="top"><p class="table">decimal | integer</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">decimal</p></td>
<td align="left" valign="top"><p class="table">[+-]?[0-9]+(\.[0-9]+)?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">integer</p></td>
<td align="left" valign="top"><p class="table">[+-]?[0-9]+</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">date</p></td>
<td align="left" valign="top"><p class="table"><em>-</em>? yyyy <em>-</em> mm <em>-</em> dd zzzzzz?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">dateTime</p></td>
<td align="left" valign="top"><p class="table"><em>-</em>? yyyy <em>-</em> mm <em>-</em> dd <em>T</em> hh <em>:</em> mm <em>:</em> ss (<em>.</em> s+)? (zzzzzz)?</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">iri</p></td>
<td align="left" valign="top"><p class="table">"   QIRI   "</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">string</p></td>
<td align="left" valign="top"><p class="table">"([^"]|\")*"/   | """([^"]|\")*""" |   /'([^']|\')*'</p></td>
</tr>
</tbody>
</table>
</div>
<h3 id="_topic_identification">2.4. Topic Identification</h3><div style="clear:left"></div>
<div class="paragraph"><p>The identification of topic items or topic types is one of the fundamental parts of a query language for topic maps. In this case the current draft has to support a simple way to address topics as parts of the query. The current draft currently supports two different types for identification of topics.</p></div>
<div class="paragraph"><p>Similar to the CTM syntax a topic item can be addressed by using one of its identifiers, its subject-identifier, subject-locator or item-identifier. The identifier will be transformed automatically by the query processor the represented topic item.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">If there are two topics using the same identifier IRI as different identifiers -  one as locators and the other as subject-identifier. The processor can not descide which topic item should be extracted. In this case the engine always prefers subject-identifiers before subject-locators and subject-locators before item-identifies.</td>
</tr></table>
</div>
<div class="listingblock">
<div class="title">Address a topic by its subject-identifier</div>
<div class="content">
<pre><tt>http://psi.ontopedia.net/Puccini</tt></pre>
</div></div>
<div class="paragraph"><p>As alternative a topic item can be addressed by the literal of its identifiers. The string literal of the IRI can be used to address a topic directly. The ambiguousness are resolved by using one of the three identification axes <em>item</em> , <em>indicators</em> or <em>locators</em>. For more information see the chapter about navigation concepts.</p></div>
<div class="listingblock">
<div class="title">Address a topic by the string literal of its subject-identifier</div>
<div class="content">
<pre><tt>"http://psi.ontopedia.net/Puccini" &lt;&lt; indicators</tt></pre>
</div></div>
<h3 id="_navigation_concept">2.5. Navigation concept</h3><div style="clear:left"></div>
<div class="paragraph"><p>In relation to the topic maps reference model ( TMRM ) a topic map is represented as an abstract bidirectional graph of construct nodes. Each node supports a number of defined axis to navigat to a related note. This concept is similar to the XPath navigation in XML documents except for the difference of a tree-structure as a special graph.</p></div>
<div class="paragraph"><p>The navigation concept of TMQL realizes a navigation through the abstract bidirectional graph of a topic map. The current draft supports a set of predefined axis on the canonical level which can be used to navigate in forward or in backward direction. Each axis supports a set of construct types which can be used as startpoint for the navigation step represented by the current axis. Some axes support an optional type filter to control the navigation step in different ways.</p></div>
<div class="paragraph"><p>The syntax of a navigation expression looks like the following production.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      NAVIGATION      ::=     STEP [ NAVIGATION ]
2:      STEP            ::=     DIRECTION AXIS [TOPIC-REF]
3:      DIRECTION       ::= &lt;&lt; | &gt;&gt;</tt></pre>
</div></div>
<div class="paragraph"><p>The following 12 sections describe each axis as stand-alone constructs. By combining the axis the user can navigate to each node of the topic map. There are no isolated nodes which cannot be accessed by a navigation.</p></div>
<h4 id="_the_indicators_axis">2.5.1. The indicators axis</h4>
<div class="paragraph"><p>The <em>indicators</em> axis represents the relationship between a topic item and its subject-identifiers. It does not support any optional type arguments and can be navigated in both directions.</p></div>
<div class="paragraph"><p>If the current node is a topic item the forward navigation returns all subject-identifiers of the current topic item as locator objects.</p></div>
<div class="paragraph"><p>If the current node is a string literal the backward navigation returns the topic represented by this subject-identifier or an empty set if there is no topic contained.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut definition contained by the non-canonical level based on the CTM syntax. The shortcut <em>~</em> returns the topic item represented by the following literal used as subject-identifier.</td>
</tr></table>
</div>
<h4 id="_the_locators_axis">2.5.2. The locators axis</h4>
<div class="paragraph"><p>The <em>locators</em> axis represents the relationship between a topic item and its subject-locators. It does not support any optional type arguments and can be navigated in both directions.</p></div>
<div class="paragraph"><p>If the current node is a topic item the forward navigation returns all subject-locators of the current topic item as locator objects.</p></div>
<div class="paragraph"><p>If the current node is a string literal the backward navigation returns the topic represented by this subject-locator or an empty set if there is no topic contained.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut definition contained by the non-canonical level based on the CTM syntax. The shortcut <em>=</em> returns the topic item represented by the following literal used as subject-locator.</td>
</tr></table>
</div>
<h4 id="_the_item_axis">2.5.3. The item axis</h4>
<div class="paragraph"><p>The <em>item</em> axis represents the relationship between a topic item and its item-identifier. It does not support any optional type arguments and can be navigate in both directions.</p></div>
<div class="paragraph"><p>If the current node is a construct the forward navigation returns one item-identifier of the current construct. In relation to the TMQL meta model, a construct only contains one item-identifier. If the number of item-identifiers is more than one, one of them will be selected at random.</p></div>
<div class="paragraph"><p>If the current node is a string literal the backward navigation returns the construct represented by this item-identifier or an empty set if there is no construct contained.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut definition contained by the non-canonical level based on the CTM syntax. The shortcut <em>^</em> returns the construct represented by the following literal used as item-identifier.</td>
</tr></table>
</div>
<h4 id="_the_id_axis">2.5.4. The id axis</h4>
<div class="paragraph"><p>The <em>id</em> axis represents the relationship between a topic map construct and its id. It does not support any optional type arguments and can be navigate in both directions.</p></div>
<div class="paragraph"><p>If the current node is a construct the forward navigation returns the id of the current construct.</p></div>
<div class="paragraph"><p>If the current node is a string literal the backward navigation returns the construct represented by this id or an empty set if there is no construct contained.</p></div>
<h4 id="_the_typed_axis">2.5.5. The typed axis</h4>
<div class="paragraph"><p>The <em>typed</em> axis represents the relationship between typed constructs and the topic type. It does not support any optional type arguments and can be navigated in both directions.</p></div>
<div class="paragraph"><p>If the current node is a typed construct the forward navigation returns the topic type of this construct.</p></div>
<div class="paragraph"><p>If the current node is a topic type the backward navigation returns all typed constructs being of this type.</p></div>
<h4 id="_the_types_axis">2.5.6. The types axis</h4>
<div class="paragraph"><p>The <em>types</em> axis represents the relationship between topic types and its instances. It does not support any optional type arguments and can be navigated in both directions.</p></div>
<div class="paragraph"><p>If the current node is a topic item the forward navigation returns all topic types of the current topic.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is an <em>instances</em> axis defined on the non-canonical level. If the current node is a topic item the backward navigation returns all topic types of the current topic, too.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">All type-instance associations handle transitive or not in relation to the pragma-definition. If the type relation handled transitive, the navigation returns all types of the whole type hierarchy, which means if A is an instance of B and B is a subtype of C than B and C are types of A.</td>
</tr></table>
</div>
<div class="paragraph"><p>If the current node is a topic type the backward navigation returns all instances of the current topic type.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is an <em>instances</em> axis defined on the non-canonical level. If the current node is a topic types the forward navigation returns all topic items which are instances of the current topic type.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">As root navigation there is an shortcut definition based on the non-canonical level. The shortcut <em>//</em> returns all instances of the topic type defined by the following topic reference.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">All type-instance associations handle transitive or not in relation to the pragma-definition. If the instance relation handled transitive, the navigation returns all instances of the whole type hierarchy, which means if A is an instance of B and B is a subtype of C than A is an instance of C.</td>
</tr></table>
</div>
<h4 id="_the_supertypes_axis">2.5.7. The supertypes axis</h4>
<div class="paragraph"><p>The <em>supertypes</em> axis represents the relationship between topic types and its supertypes. It does not support any optional type arguments and can be navigated in both directions.</p></div>
<div class="paragraph"><p>If the current node is a topic type the forward navigation returns all topic types acts as supertypes of the current topic type.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is an <em>subtypes</em> axis defined on the non-canonical level. If the current node is a topic type the backward navigation returns all topic types acts as supertypes of the current topic, too.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">All supertype-subtype associations handle transitive or not in relation to the pragma-definition. If the supertype relation handled transitive, the navigation returns all supertypes of the whole type hierarchy, which means if A is a subtype of B and B is a subtype of C than B and C are supertypes of A.</td>
</tr></table>
</div>
<div class="paragraph"><p>If the current node is a topic type the backward navigation returns all topic types acts as subtypes of the current topic type.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is an <em>subtypes</em> axis defined on the non-canonical level. If the current node is a topic types the forward navigation returns all topic types acts as subtypes of the current topic type.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">All supertype-subtype associations handle transitive or not in relation to the pragma-definition. If the subtype relation handled transitive, the navigation returns all subtypes of the whole type hierarchy, which means if A is a subtype of B and B is a subtype of C than A and B are subtypes of C.</td>
</tr></table>
</div>
<h4 id="_the_characteristics_axis">2.5.8. The characteristics axis</h4>
<div class="paragraph"><p>The <em>characteristics</em> axis represents the relationship between a topic item and its characteristics ( merged concept of names and occurrences ). The axis supports a optional type in both directions.</p></div>
<div class="paragraph"><p>If the current node is a topic item the forward navigation returns all characteristic items of the current topic item. If the optional type is used only characteristics of the specified type will be returned.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There are special predefined topic references to identify the TMDM <em>name-type</em> and <em>occurrence-type</em> as optional type arguments of the characteristics axis. The topic reference <em>tm:name</em> used as optional type argument of the <em>characteristics</em> axis will return all characteristics which represent a name item in the meaning of the TMDM. The topic reference <em>tm:occurrence</em> used as optional type argument of the <em>characteristics</em> axis will return all characteristics which represent an occurrence item in the meaning of the TMDM.</td>
</tr></table>
</div>
<div class="paragraph"><p>If the current node is a charcteristics item the backward navigation returns the topic item related to this characteristics item. If the optional type is used only topic items being an instance of the specified type will be returned.</p></div>
<h4 id="_the_atomify_axis">2.5.9. The atomify axis</h4>
<div class="paragraph"><p>The <em>atomify</em> axis represents the relationship between a characteristics or locator object and its literal. The axis does not support any optional type argument and can be navigated in both directions.</p></div>
<div class="paragraph"><p>If the current node is a characteristics item the forward navigation returns the literal representing the value of the characteristics item. The literal will be interpreted in relation to the datatype of the characteristics item and will be casted automatically. If the current node is a locator object the forward navigation returns the string literal representing the IRI of this locator object.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">If a characteristic or locator item compared with a literal it will be atomified automatically.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut definition as a part of the non-canonical level representing the combination of the <em>characteristics</em> and <em>atomify</em> axis. The shortcut <em>/</em> returns the literals of all characteristics of the topic item addressed by the current node. Please note that the optional type can not be left out by using this shortcut, it is obligatory .</td>
</tr></table>
</div>
<div class="paragraph"><p>If the current node is a string literal the backward navigation returns all characteristic items or locator items using exactly this literal as value.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut definition as a part of the non-canonical level representing the combination of the <em>characteristics</em> and <em>atomify</em> axis. The shortcut <em>\</em> returns all topics related to at least one characteristics or locators represented by there literal. Please note that the optional type can not be left out by using this shortcut, it is obligatory .</td>
</tr></table>
</div>
<h4 id="_the_players_axis">2.5.10. The players axis</h4>
<div class="paragraph"><p>The <em>players</em> axis represents the relationship between an association item and its players. The optional type argument is supported in both directions.</p></div>
<div class="paragraph"><p>If the current node is an association item the forward navigation returns all topic items being a player of the current association item. If the optional type is used only the topic items being the player of the role type specified by the optional type will be returned. If the current node is a topic type, at first all association items of the topic type will be extracted.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut contained by the non-canonical level. The shortcut <em>&#8594;</em> returns all players of the association item specified by the current node. The optional type can be used similar to the canonical production.</td>
</tr></table>
</div>
<div class="paragraph"><p>If the current node is a topic item the backward navigation returns all association items played by the topic item. If the optional type is used only the association items will returned using the topic item as a player of the role typed by the optional type.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut contained by the non-canonical level. The shortcut <em>&#8592;</em> returns all associations played by the topic item specified by the current node. The optional type can be used similar to the canonical production.</td>
</tr></table>
</div>
<h4 id="_the_roles_axis">2.5.11. The roles axis</h4>
<div class="paragraph"><p>The <em>roles</em> axis represents the relationship between an association item and its role types. The optional type argument only support for backward navigations.</p></div>
<div class="paragraph"><p>If the current node is an association item the forward navigation returns all topic types acts as role types of the association. If the current node is a topic type, at first all association items of the topic type will be extracted.</p></div>
<div class="paragraph"><p>If the current node is a topic type the backward navigation returns all association items using the topic type as a role type. The optional type has no relevance.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">In addition to the current draft some implementions of the query language supporting an optional type argument. If the optional type is used the backward navigation only returns association items of the defined association type.</td>
</tr></table>
</div>
<h4 id="_the_traverse_axis">2.5.12. The traverse axis</h4>
<div class="paragraph"><p>The <em>traverse</em> axis represents the relationship between topic items, playing the same association items. The type argument can be used in both directions.</p></div>
<div class="paragraph"><p>If the current node is a topic item the forward navigation returns all topic items connected the current node by playing at least one association item with it. If the optional type is used only topic items connected through an association item of the optional type are returned.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut definition contained by the non-canonical level. The shortcut <em>&lt;&#8594;</em> returns all connected topic items. The optional type can be used in the same way like the canonical production.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The result can contains a topic item multiple times, if it is connected through more than one association item.</td>
</tr></table>
</div>
<div class="paragraph"><p>If the current node is an association item the backward navigation returns all association items connected by using the same playing topic item. The optional type has no relevance.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The result can contains an association item multiple times, if it is connected through more than one topic item.</td>
</tr></table>
</div>
<h4 id="_the_scope_axis">2.5.13. The scope axis</h4>
<div class="paragraph"><p>The <em>scope</em> represents the relationship between an association item or an characteristic item and its scoping topics. The optional type is not supported.</p></div>
<div class="paragraph"><p>If the current node is an association item or an characterisitic item the forward navigation returns all themes of the scope of that constructs.</p></div>
<div class="paragraph"><p>If the current node is a topic item the backward navigation returns all association items and characteristic items containing the topic item as one theme of their scope.</p></div>
<h4 id="_the_reifier_axis">2.5.14. The reifier axis</h4>
<div class="paragraph"><p>The <em>reifier</em> represents the relationship between an association item or an characteristic item and its reifing topic item. The optional type has no relevance.</p></div>
<div class="paragraph"><p>If the current node is an association item or an chracteristic item the forward navigation returns the topic item used as reifier of the current construct.</p></div>
<div class="paragraph"><p>If the current node is a topic item the backward navigation returns the association item or characteristic item using the topic item as reifier.</p></div>
<h3 id="_the_environment">2.6. The Environment</h3><div style="clear:left"></div>
<div class="paragraph"><p>The draft of topic maps query language specifies a predefined environment represented as a topic map. The predefined environment contains a set of predefined functions, a set of operators, a set of predefined topic references, a set of prefixes and additonal ontology information.</p></div>
<h4 id="_predefined_prefixes">2.6.1. Predefined prefixes</h4>
<div class="paragraph"><p>In the context of a TMQL query a topic will be represented by a subject-identifier, subject-locator or item-identifier. Each of this identifiers are represented by a string-represented IRI which has to be known by the underlying topic maps engine. Related to a model, the most identifiers of a topic map will be similar to each other in relation to their IRI string literals, except from a short part at the end of the IRI literal. The identifiers use the same prefix and because of using a set of topics as part of the query we have to write a set of many identifiers only differs in a short part at the end. The solution of this problem is to define a number of prefixes and use relative IRIs instead of the absolute one.</p></div>
<div class="paragraph"><p>There are some predefined prefixes defined by the current draft of the topic maps query language which can be used without defining explicitly. The following prefixes are contained by the predefined environment.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="12%" />
<col width="25%" />
<col width="62%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>prefix literal</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>absolute IRI</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>description</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm</p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/iso13250/model/">http://psi.topicmaps.org/iso13250/model/</a></p></td>
<td align="left" valign="top"><p class="table">This is the namespace for the concepts defined by TMDM (via the TMDM/TMRM mapping).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">xsd</p></td>
<td align="left" valign="top"><p class="table"><a href="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</a>#</p></td>
<td align="left" valign="top"><p class="table">This is the namespace for the XML Schema Datatypes.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tmql</p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/">http://psi.topicmaps.org/tmql/1.0/</a></p></td>
<td align="left" valign="top"><p class="table">Under this prefix the concepts of TMQL itself are located.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">fn</p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/">http://psi.topicmaps.org/tmql/1.0/functions/</a></p></td>
<td align="left" valign="top"><p class="table">Under this prefix user-callable functions of the predefined TMQL environment are located.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">dc</p></td>
<td align="left" valign="top"><p class="table"><a href="http://purl.org/dc/terms/">http://purl.org/dc/terms/</a></p></td>
<td align="left" valign="top"><p class="table">Under this prefix Dublin Core elements are located.</p></td>
</tr>
</tbody>
</table>
</div>
<h4 id="_predefined_functions_and_operators">2.6.2. Predefined functions and operators</h4>
<div class="paragraph"><p>Similar to the other query languages like SQL, the current draft specify a number of functions which can be used to transform tuples or sequences. Each function are represented by a topic as a part of the environment topic map of the runtime container and can be used as part of the TMQL query like each other topic reference. In addition TMQL define a expression type called <em>function-invocation</em> to call a function with a list of arguments. Each function will be addressed by a topic item reference and a tuple-expression to define the parameter list given to the function interpreter.</p></div>
<h5 id="_string_concat">string concat</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-concat">http://psi.topicmaps.org/tmql/1.0/functions/string-concat</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table"><br /></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-concat (a : string, b : string) return string</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">2</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-concat</em> combines a set of strings. The function expects exactly two arguments given by the following tuple-expression. The type of the argument can be simple strings or sets of strings and the result will be a set of strings or a simple string. The behaviour of the function is dependent from the given argument type. If the first argument <em>a</em> is a string and the second argument <em>b</em> two, the method will return the string combination of <em>a</em> and <em>b</em>. If one of the arguments <em>a</em> or <em>b</em> is a set of strings the method will return a set of strings containing each combination of the atomic string and each string of the given set. If both arguments are sets the method will return each combination of each string of the first set and the second set.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-concat ( a =&gt; [ "foo" ] , b =&gt; [ "bar" ] )
2:      =&gt; "foobar"
3:
4:      fn:string-concat ( a =&gt; [ "foo" , "main" ] , b =&gt; [ "bar" ] )
5:      =&gt; [ "foobar" , "mainbar" ]
6:
7:      fn:string-concat ( a =&gt; [ "foo" , "main" ] , b =&gt; [ "bar" , "menu" ] )
8:      =&gt; [ "foobar" , "mainbar" , "foomenu" , "mainmenu" ]</tt></pre>
</div></div>
<h5 id="_string_length">string-length</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-length">http://psi.topicmaps.org/tmql/1.0/functions/string-length</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:length (s : string) return integer</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>length</em> returns the internal size of a string literal by counting the contained characters. The function expect exactly one argument which can be a simple string or a sequence of strings. The behaviour of the function is dependent from the given argument type. If the argument is a simple string the function return a single integer value. If the argument is a set of strings it will return a sequence of integer values.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:length ( s =&gt; [ "foo" ]  )
2:      =&gt; 3
3:
4:      fn:length ( s =&gt; [ "foo" , "main" ] )
5:      =&gt; [ 3 , 4 ]</tt></pre>
</div></div>
<h5 id="_string_less_than">string-less-than</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-less-than">http://psi.topicmaps.org/tmql/1.0/functions/string-less-than</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&lt;</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-lt (a : string, b : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-lt</em> compare the two string literals and only return the string literal given by the first argument if the literal is lexicographically lower than the second string. The function expected two arguments which has be of the type string. The first argument also can be a sequence of strings. The behaviour of the function is dependent from the given argument type. If the first argument is a set of strings the function returns a set containing the lexicographically lower string in relation to the second string argument. If the first argument is a string it return the given string if it is lexicographically lower than the second one, otherwise it return an empty set. If the second argument is a set of strings the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-lt ( a =&gt; [ "a" ] , b =&gt; [ "aaa" ] )
2:      =&gt; "a"
3:
4:      fn:string-lt ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" ] )
5:      =&gt; "a"
6:
7:      fn:string-lt ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" , "bbb" ] )
8:      =&gt; "a"</tt></pre>
</div></div>
<h5 id="_string_less_equal_than">string-less-equal-than</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-less-equal-than">http://psi.topicmaps.org/tmql/1.0/functions/string-less-equal-than</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&lt; =</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-leq (a : string, b : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-leq</em> compare the two string literals and only return the string literal given by the first argument if the literal is lexicographically lower or equal than the second string. The function expected two arguments which has be of the type string. The first argument also can be a sequence of strings. The behaviour of the function is dependent from the given argument type. If the first argument is a set of strings the function returns a set containing the lexicographically lower string in relation to the second string argument. If the first argument is a string it return the given string if it is lexicographically lower or equal than the second one, otherwise it return an empty set. If the second argument is a set of strings the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-leq ( a =&gt; [ "a" ] , b =&gt; [ "aaa" ] )
2:      =&gt; "a"
3:
4:      fn:string-leq ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" ] )
5:      =&gt; "a"
6:
7:      fn:string-leq ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" , "bbb" ] )
8:      =&gt; "a"</tt></pre>
</div></div>
<h5 id="_string_greater_equal_than">string-greater-equal-than</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-greater-equal-than">http://psi.topicmaps.org/tmql/1.0/functions/string-greater-equal-than</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&gt;=</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-geq (a : string, b : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-geq</em> compare the two string literals and only return the string literal given by the first argument if the literal is lexicographically greater or equal than the second string. The function expected two arguments which has be of the type string. The first argument also can be a sequence of strings. The behaviour of the function is dependent from the given argument type. If the first argument is a set of strings the function returns a set containing the lexicographically greater string in relation to the second string argument. If the first argument is a string it return the given string if it is lexicographically greater or equal than the second one, otherwise it return an empty set. If the second argument is a set of strings the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-geq ( a =&gt; [ "a" ] , b =&gt; [ "aaa" ] )
2:      =&gt; [ ]
3:
4:      fn:string-geq ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" ] )
5:      =&gt; "b"
6:
7:      fn:string-geq ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" , "bbb" ] )
8:      =&gt; "b"</tt></pre>
</div></div>
<h5 id="_string_greater_than">string-greater-than</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-greater-than">http://psi.topicmaps.org/tmql/1.0/functions/string-greater-than</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&gt;</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-gt (a : string, b : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-gt</em> compare the two string literals and only return the string literal given by the first argument if the literal is lexicographically greater than the second string. The function expected two arguments which has be of the type string. The first argument also can be a sequence of strings. The behaviour of the function is dependent from the given argument type. If the first argument is a set of strings the function returns a set containing the lexicographically greater string in relation to the second string argument. If the first argument is a string it return the given string if it is lexicographically greater than the second one, otherwise it return an empty set. If the second argument is a set of strings the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-gt ( a =&gt; [ "a" ] , b =&gt; [ "aaa" ] )
2:      =&gt; [ ]
3:
4:      fn:string-gt ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" ] )
5:      =&gt; "b"
6:
7:      fn:string-gt ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" , "bbb" ] )
8:      =&gt; "b"</tt></pre>
</div></div>
<h5 id="_string_regexp_match">string-regexp-match</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-regexp-match">http://psi.topicmaps.org/tmql/1.0/functions/string-regexp-match</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">=~</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:regexp (s : string, re : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>regexp</em> checks if the given string argument matches to the regular expression. The method expected exactly two arguments, which can be an instance of string or a simple sequence or strings. The behaviour of the function is dependent from the given argument type. If the first argument is a simple string, the result will be an empty sequence if the string does not match or the string if it matches. If the first argument is a set of strings the function will return a set of all matching strings. If the second argument is a set of strings only the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:regexp ( a =&gt; [ "aaa" ] , b =&gt; [ "[a]+" ] )
2:      =&gt; "aaa"
3:
4:      fn:regexp ( a =&gt; [ "aaa" , "bbb" ] , b =&gt; [ "[a]+" ] )
5:      =&gt; "aaa"
6:
7:      fn:regexp ( a =&gt; [ "aaa" , "bbb" ] , b =&gt; [ "[a]+" , "[b]+" ] )
8:      =&gt; "aaa"</tt></pre>
</div></div>
<h5 id="_substring">substring</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/substring">http://psi.topicmaps.org/tmql/1.0/functions/substring</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:substring (s : string, f : interger , t : interger ) return string</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>substring</em> will be return an substring of the given string argument addressed by the given indexes. The function expects exactly three arguments of type string and integer. As first argument a string sequence is supported two. The behaviour of the function is dependent from the given arguments. If the first argument is a string it will return a single string representing the substring of the first argument. If the first argument is a sequence it will return a sequence of substrings. If any of the indexes is out of bounds the function will clear this indexes to the possible values which are encapsulate by the given range. The string indexes will be zero-based and the upper index will be excluded.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:substring ( s =&gt; [ "Java-based engine" ] , f =&gt; 1 , t =&gt; 5 )
2:      =&gt; "ava-"
3:
4:      fn:substring ( s =&gt; [ "Java-based engine" , "foo" ] , f =&gt; 1 , t =&gt; 5 )
5:      =&gt; [ "ava-" , "oo" ]
6:
7:      fn:substring ( s =&gt; [ "Java-based engine" , "foo" ] , f =&gt; -1 , t =&gt; 50 )
8:      =&gt;  [ "Java-based engine" , "foo" ]
9:
10:     fn:substring ( s =&gt; [ "Java-based engine" , "foo" ] , f =&gt; "1" , t =&gt; "5" )
11:     =&gt;  [ "ava-" , "oo" ]
12:
13:     fn:substring ( s =&gt; [ "Java-based engine" , "foo" ] , f =&gt; "a" , t =&gt; "5" )
14:     =&gt;  raises an error</tt></pre>
</div></div>
<h5 id="_has_datatype">has-datatype</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/has-datatype">http://psi.topicmaps.org/tmql/1.0/functions/has-datatype</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:has-datatype (s: tuple-sequence) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>has-datatype</em> retrieves the data type for each tuple element in each tuple. The function expects exactly one argument which has to be a tuple or a tuple sequence. The behaviour of the functions is dependent from the given arguments. If the the contained element is a name item the data type will be <em>string</em>, for occurrence item  it will be the internal data type and for each atom it will be the data type of the atom itself. Any other item results in the data type <em>any</em>. Each data type is a IRI.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:has-datatype ( s =&gt; [ "http://tmql4j.topicmapslab.de"^^xsd:anyURI , "aaa" , 5 ] )
2:      =&gt;  [ "xsd:anyURI" , "xsd:string" , "xsd:interger" ]</tt></pre>
</div></div>
<h5 id="_has_variant">has-variant</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/has-variant">http://psi.topicmaps.org/tmql/1.0/functions/has-variant</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:has-variant (s: tuple-sequence, s: item-reference) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function has-variant only supported for topic name items. The function expected exactly two argument which has to be a tuple sequence and a topic reference. It retrieves the variant items for each tuple element in each tuple the variant name for the given scope. For name items this is the variant value, if such exists. Otherwise it is undef. For all other things the function will return ever undef.</p></div>
<h5 id="_slice">slice</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/slice">http://psi.topicmaps.org/tmql/1.0/functions/slice</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:slice (s : tuple-sequence, low : integer, high : integer) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>slice</em> is a function supports tuple-sequences. The method returns the selected tuples of the sequence with an index between the given arguments. The indexes are zero-based and the upper index will be excluded. If the indexes given as strings, it will be transformed to interger values automatically. The function will be used by the select expression to realize the keywords <em>LIMIT</em> and <em>OFFSET</em>. If the interger values are negative or invalid an error will be raised. If the indexes are out of bounds the function will return the tuples with an index in range of the tuple-sequence and the given arguments.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:slice  ( s =&gt; [ "a" , "b" , "c" , "d" ] , low =&gt; 1 , high =&gt; 2 )
2:      =&gt; [ "a" ]
3:
4:      fn:slice  ( s =&gt; [ "a" , "b" , "c" , "d" ] , low =&gt; 3 , high =&gt; 10 )
5:      =&gt; [ "c" , "d" ]
6:
7:      fn:slice  ( s =&gt; [ "a" , "b" , "c" , "d" ] , low =&gt; "a" , high =&gt; "-1" )
8:      =&gt;  raises an error</tt></pre>
</div></div>
<h5 id="_count">count</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/count">http://psi.topicmaps.org/tmql/1.0/functions/count</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:count (s : tuple-sequence) return integer</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>count</em> returns the number of tuples of the tuple sequence. The function expected one argument which should be a tuple sequence or an atom. The behaviour of the function is dependent from given arguments. If an atom is given the method will return 1 every time. If it is an tuple sequence it will return the number of contained items.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:count  ( s =&gt; [ "a" , "b" , "c" , "d" ]  )
2:      =&gt; 4
3:
4:      fn:count  ( s =&gt; "b" )
5:      =&gt; 1
6:
7:      fn:count  ( s =&gt; [ ] )
8:      =&gt;  0</tt></pre>
</div></div>
<h5 id="_uniq">uniq</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/uniq">http://psi.topicmaps.org/tmql/1.0/functions/uniq</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:uniq (s : tuple-sequence) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>uniq</em> unifies the given tuple sequence. As an interpretation of the current draft each tuple sequence can contain each tuple multiple times. The function removes all multiple references of the same tuple in the given sequence. As arguments the function expects exactly one tuple sequences. The functions is used by the select expression to realize the keyword <em>UNIQUE</em>. The indexes of the tuples in the tuple sequence will be changed.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:uniq  ( s =&gt; [ "a" , "b" , "a" , "b" ]  )
2:      =&gt; [ "a" , "b" ]</tt></pre>
</div></div>
<h5 id="_concat">concat</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/concat">http://psi.topicmaps.org/tmql/1.0/functions/concat</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">UNION</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:concat (s : tuple-sequence, t : tuple-sequence) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">1</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>concat</em> combine two tuple sequence to a new one. The functions adds all tuples of the second sequence to the first sequence. If one of the arguments is an atom instead of a sequence, a new sequence will be created and the atoms will be added. While the combination any ordering is honored.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:concat  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt; "a" )
2:      =&gt; [ "a" , "b" , "a" , "b" , "a" ]
3:
4:      fn:concat  ( s =&gt; "a"  , t =&gt; "b" )
5:      =&gt; [ "a" , "b" ]
6:
7:      fn:concat  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt;  [ "a"  , "c" ] )
8:      =&gt; [ "a" , "b" , "a" , "b" , "a" , "c" ]</tt></pre>
</div></div>
<h5 id="_except">except</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/except">http://psi.topicmaps.org/tmql/1.0/functions/except</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">MINUS</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:except (s : tuple-sequence, t : tuple-sequence) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">1</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>except</em> produces a tuple sequence where all tuple which appear in t are removed from s. If one of the arguments is an atom instead of a sequence, a new sequence will be created an the atoms will be added. There is no effect for the ordering. If the first tuple sequence contains an element of the second one multiple times, all references of this element will be removed.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:except  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt; "a" )
2:      =&gt; [ "b" , "b" ]
3:
4:      fn:except  ( s =&gt; "a"  , t =&gt; "b" )
5:      =&gt; [ "a" ]
6:
7:      fn:except  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt;  [ "a"  , "c" ] )
8:      =&gt; [ "b" , "b" ]</tt></pre>
</div></div>
<h5 id="_compare">compare</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/compare">http://psi.topicmaps.org/tmql/1.0/functions/compare</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">INTERSECT</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:compare (s : tuple-sequence, t : tuple-sequence) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">1</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>compare</em> produces a tuple sequence of all tuples which appear in s and t. Any tuple of the sequence s which is not contained by t will be removed from s. If one of the arguments is an atom instead of a sequence, a new sequence will be created an the atoms will be added. There is no effect for the ordering. The number of references of a tuple element will not be considered.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:compare  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt; "a" )
2:      =&gt; [ "a" , "a" ]
3:
4:      fn:compare  ( s =&gt; "a"  , t =&gt; "b" )
5:      =&gt; [ ]
6:
7:      fn:compare  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt;  [ "a"  , "c" ] )
8:      =&gt; [ "a" , "a" ]</tt></pre>
</div></div>
<h5 id="_zigzag">zigzag</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/zigzag">http://psi.topicmaps.org/tmql/1.0/functions/zigzag</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:zigzag (s : tuple-sequence) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>zigzag</em> is the reverse function of <em>zagzig</em> and returns a single tuple filled with all values from all tuples. The function can be used to speed up the application because indexes of tuples run faster than indexes within the tuple sequence.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:zigzag  ( s =&gt; [ [ "a" , "b" ] , [ "a" , "b" ] )
2:      =&gt; [ "a" , "b" , "a" , "b" ]
3:
4:      fn:zigzag  ( s =&gt; [ "a" , [ "a" , "b" ] )
5:      =&gt; [ "a" , "a" , "b" ]</tt></pre>
</div></div>
<h5 id="_zagzig">zagzig</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/zagzig">http://psi.topicmaps.org/tmql/1.0/functions/zagzig</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:zagzig (s : tuple-sequence) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>zagzig</em> is the reverse function of <em>zigzag</em> and returns a tuple sequence filled by singleton tuples containing an element of the origin tuple. The index of the singleton tuple in context of the sequence will be the same than the index of the item contained by the new singleton tuple in context of the origin tuple.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:zagzig  ( s =&gt;  [ "a" , "b" , "a" , "b" ] )
2:      =&gt; ( [ "a" ] , [ "a" ] , [ "a" ] , [ "a" ] )</tt></pre>
</div></div>
<h5 id="_url_decode">url-decode</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/url-decode">http://psi.topicmaps.org/tmql/1.0/functions/url-decode</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:url-decode (s : string) return string</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>url-decode</em> decodes the given URL reference. The result will be the reference without any encoded characters.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:url-decode  ( s =&gt;  "http://psi.example.org/Hello%20World" )
2:      =&gt; ( "http://psi.example.org/Hello World" )</tt></pre>
</div></div>
<h5 id="_url_encode">url-encode</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/url-encode">http://psi.topicmaps.org/tmql/1.0/functions/url-encode</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:url-encode (s : string) return string</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>url-encode</em> encodes the given string literal as an URI reference and escape all forbidden characters of the URI syntax.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:url-encode  ( s =&gt;  "http://psi.example.org/Hello World" )
2:      =&gt; ( "http://psi.example.org/Hello%20World" )</tt></pre>
</div></div>
<h4 id="_predefined_topic_references">2.6.3. Predefined topic references</h4>
<div class="paragraph"><p>In adaptation to the topic maps meta model there are some predefined topic references which can be used as topic reference in the query. The following table contains all predefined references and a short description of their meaning. In this context the prefix <em>tm</em> is used for the full qualified IRI <em>http://psi.topicmaps.org/iso13250/model/</em>.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="16%" />
<col width="83%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>topic reference</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>description</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:subject</p></td>
<td align="left" valign="top"><p class="table">Representing the <em>topic-type</em> of the TMDM. Every topic item and topic type is an instance of this topic type. Can be used as a wildcard for undefined topic actors.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:name</p></td>
<td align="left" valign="top"><p class="table">Representing the <em>name-type</em> of the TMDM. Every name item is an instance of this type. Can be used to filter characteristics representing a name item in the meaning of the TMDM.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:occurrence</p></td>
<td align="left" valign="top"><p class="table">Representing the <em>occurrence-type</em> of the TMDM. Every occurrence item is an instance of this type. Can be used to filter characteristics representing an occurrence item in the meaning of the TMDM.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:subclass-of</p></td>
<td align="left" valign="top"><p class="table">Representing the type of the <em>supertype-subtype</em> associations of the TMDM. Can be used as association type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:subclass</p></td>
<td align="left" valign="top"><p class="table">Representing the type of the <em>subtype</em> role of the TMDM. Can be used as role type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:superclass</p></td>
<td align="left" valign="top"><p class="table">Representing the type of the <em>supertype</em> role of the TMDM. Can be used as role type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:type-instance</p></td>
<td align="left" valign="top"><p class="table">Representing the type of the <em>type-instance</em> associations of the TMDM. Can be used as association type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:instance</p></td>
<td align="left" valign="top"><p class="table">Representing the type of the <em>instance</em> role of the TMDM. Can be used as role type.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm:type</p></td>
<td align="left" valign="top"><p class="table">Representing the type of the <em>type</em> role of the TMDM. Can be used as role type.</p></td>
</tr>
</tbody>
</table>
</div>
<h4 id="_environment_clause">2.6.4. Environment clause</h4>
<div class="paragraph"><p>To change the environment in the context of one query the current draft supports a special expression type to add additional information to control the querying process. An <em>environment clause</em> can be add the beginning of a query to define additional environment information. The production looks like the following one.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      ENVIRONEMT-CLAUSE       ::= { DIRECTIVE | PRAGMA }
2:      DIRECTIVE               ::= PREFIX
3:      PREFIX                  ::= '%prefix' IDENTIFIER QIRI
4:      PRAGMA                  ::= '%pragma' IDENTIFIER QIRI</tt></pre>
</div></div>
<div class="paragraph"><p>A prefix directive can be used to define a prefix only valid for the following query. The prefixes defined by a triple containing the keyword <em>%prefix</em> the prefix identifier and the full qualified IRI of the prefix.</p></div>
<div class="paragraph"><p>A pragma definition contains additional information to control the querying process. Currently the draft only supports one pragma identifier describing the transitivity of the type hierarchy. The pragma definition identified by the identifier <em>taxonometry</em>. There are two possible QIRI representing the value of the pragma definition. The identifier <em>tm:transitive</em> represent a type hierarchy handled transitive. The opposit value <em>tm:intransitive</em> used to handle the hierarchy intransitive.</p></div>
<h3 id="_variables_and_bindings">2.7. Variables and bindings</h3><div style="clear:left"></div>
<div class="paragraph"><p>During the querying process variables are bind to different values. The processor bind the variable to value contained by the binding definition. During the iteration each value will be checked for satisfation and validity.</p></div>
<div class="paragraph"><p>A variable has to start with the prefix <em>$</em> followed by a number of alphanumerical characters or an underscore character. The variable can be postfixed by number of primes. If two variables has the same name except their number of postfixed primes, the processor interpret them as protected variable sub set. Protected variables cannot be bind to the same value in one iteration.</p></div>
<div class="paragraph"><p>The possible bindings of a variable are defined by a variable binding definition called <em>variable-assignment</em>. A binding set is a special expression type containing a number of variable assignments. Each variable-assignment looks like the following production.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      BINDING-SET             ::=     &lt; VARIABLE-ASSIGNMENT &gt;
2:      VARIABLE-ASSIGNMENT ::= VARIABLE 'IN' CONTENT</tt></pre>
</div></div>
<div class="paragraph"><p>The <em>content</em> expression returns a set of topic map items which can be bind to the variable represented by their name.</p></div>
<h4 id="_predefined_variables">2.7.1. Predefined variables</h4>
<div class="paragraph"><p>The current draft contains a number of predefined variables which will be reserved by the processor. The following table contains all predefined variables of the TMQL draft.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="16%" />
<col width="83%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>variable</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>description</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">%_</p></td>
<td align="left" valign="top"><p class="table">Representing the queried topic map itselfs.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">@_</p></td>
<td align="left" valign="top"><p class="table">Representing the current tuple in the context of the iteration over possible variable bindings.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">$#</p></td>
<td align="left" valign="top"><p class="table">Representing the current index of the tuple in the context of the tuple sequence. The index can be used to filter tuples by their index.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">$[0-9]+</p></td>
<td align="left" valign="top"><p class="table">Representing the tuples of a tuple sequence similar to the variable <em>$#</em>. The variable <em>$0</em> bound to the tuple at the first index, <em>$1</em> to the tuple at the second and so on.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">$_</p></td>
<td align="left" valign="top"><p class="table">Representing anonymous write-only variables which can be used as placeholder if the variable binding is not necessary.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>All this variables are read-only variables except the anonymous variable. This variable is an write-only variable which can be used if their binding is not necessary for the query result. Anonymous variables are simply like wildcards.</p></div>
<h3 id="_boolean_expressions_and_boolean_primitives">2.8. Boolean expressions and boolean primitives</h3><div style="clear:left"></div>
<div class="paragraph"><p>To define conditions which should be satisfied by the items contained in the result set, the draft supports boolean expressions representing the combination of boolean primitves. A booleam primitive represent an atomic condition for example a type or scope matching.</p></div>
<div class="paragraph"><p>In the context of query booleaqn expressions and boolean primitives can be used at different positions, for example as filter definitions after navigation steps or as a part of where-clauses. For more information please take a look at the corresponding chapter.</p></div>
<div class="paragraph"><p>There are different types of boolean primitves and boolean combinations. This chapter give a short overview about boolean primitives and their combinations using boolean expressions.</p></div>
<h4 id="_instance_of_expressions">2.8.1. Instance-of expressions</h4>
<div class="paragraph"><p>The <em>instance-of expression</em> or <em>ISA-expression</em> is contained by the non-canonical level of the query language and describe the type-instance relation of a topic type and an instance represented by a topic item. The expression should be used to bind variables only to instances of a specific type. In this context a variable will be bind only to instances of this specific type. The production of an <em>instance-of expression</em> is quite simple and looks like the following definintion.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      ISA-EXPRESSION          ::=     VALUE-EXPRESSION 'ISA' VALUE-EXPRESSION
2:      VALUE-EXPRESSION        ::=     VARIABLE | TOPIC-REF | ATOM</tt></pre>
</div></div>
<div class="paragraph"><p>An instance-of expression symbolized by the keyword <em>ISA</em> which will be reserved for this expression type. The first value-expression in front of the keyword represents the instance. Normally the first value-expression only contains a variable which will be bind to different topic map items. The second value expression represents the topic type which will be represented by a topic reference or a navigation expression. The expression returns <em>true</em> only if the value-expression in front of the keyword returns a topic item being an instance of the topic type returned by the second value-expression. If the first value-expression is represented as a variable the set of possible variable bindings will be reduced to all instances of the topic type returned by the second value-expression.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The production is only valid on the non-canonical level. The expression can be replaced by its canonical counterpart representing a <em>predicate-invocation</em> with the predefined type of a <em>type-instance</em> associaton and the predefined role types.</td>
</tr></table>
</div>
<h4 id="_kind_of_expressions">2.8.2. Kind-of expressions</h4>
<div class="paragraph"><p>The <em>kind-of expression</em> or <em>AKO-expression</em> is contained by the non-canonical level of the query language and describe the supertype-subtype relation of a topic type and its supertypes. The expression should be used to bind variables only to subtypes of a specific type. In this context a variable will be bind only to subtypes of this specific type. The production of an <em>kind-of expression</em> is quite simple and looks like the following definintion.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      AKO-EXPRESSION          ::=     VALUE-EXPRESSION 'AKO' VALUE-EXPRESSION
2:      VALUE-EXPRESSION        ::=     VARIABLE | TOPIC-REF | ATOM</tt></pre>
</div></div>
<div class="paragraph"><p>A kind-of expression symbolized by the keyword <em>AKO</em> which will be reserved for this expression type. The first value-expression in front of the keyword represents the subtype. Normally the first value-expression only contains a variable which will be bind to different topic map items. The second value expression represents the supertype which will be represented by a topic reference or a navigation expression. The expression returns <em>true</em> only if the value-expression in front of the keyword returns a topic type being a subtype of the topic type returned by the second value-expression. If the first value-expression is represented as a variable the set of possible variable bindings will be reduced to all subtypes of the topic type returned by the second value-expression.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The production is only valid on the non-canonical level. The expression can be replaced by its canonical counterpart representing a <em>predicate-invocation</em> with the predefined type of a <em>supertype-subtype</em> associaton and the predefined role types.</td>
</tr></table>
</div>
<h4 id="_predicate_invocations">2.8.3. Predicate invocations</h4>
<div class="paragraph"><p>One of the fundamental concept of a topic map are association items. An association item is used to define a relationship between a set of topic items and representing a defined semantic meaning. Each topic item can act as a player in the context of different role types.</p></div>
<div class="paragraph"><p>The importance of association items indicates that necessity of modelling associations as a part of a query. To realize the definition of relations between topic items as a condition, the topic maps query language contains the special expression type called <em>predicate-invocation</em>. The syntax of predicates is similar to the CTM syntax to define associations.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      PREDICATE-INVOCATION    ::= TOPIC-REF '(' &lt; TYPE-PLAYER-DEFINITION &gt; ')'
2:      TYPE-PLAYER-DEFINITION  ::=     TOPIC-REF ':' VALUE-EXPRESSION | '...'</tt></pre>
</div></div>
<div class="paragraph"><p>The <em>predicate-invocation</em> starts with a topic reference representng the association type followed by a set of type-player definitions for a specific role construct. If the association type does not exists an error will be raised by the query processor. A predicate can contain a unquantified number of role constraints define a type-player combination which has to be satisfied by an association item. A role type will be represented by a topic reference and the player can be a topic reference or a variable. If the player is bound to a variable the condition checks if the variable is bind to a topic reference playing the specific role in one association item with the other constraints. Each constraint must be satsified by the association item.</p></div>
<div class="paragraph"><p>In contrast to the Tolog query language this operation is strict, which means that the association item has to satisify exactly the constraints defined and must not contain any other role construct than defined by the set of constraints. To handle them as non-strict operation the ellipsis <em>&#8230;</em> has to be used at the end of role-constraints.</p></div>
<h4 id="_quantified_expressions">2.8.4. Quantified expressions</h4>
<div class="paragraph"><p>Quantified expressions are special boolean primitives checks a boolean condition in combination with a numerical restriction of satistying items.</p></div>
<div class="paragraph"><p>A quantified expression define a sub set of variables bindings which will be checked for satisfaction of the given boolean condition. The number of satifying items depends on the type of quantified expression and can be defined as upper or lower bound. Quantified expressions can be split into two types <em>for-all clauses</em> and <em>exists clauses</em>.</p></div>
<h5 id="_forall_clauses">Forall clauses</h5>
<div class="paragraph"><p>The production of for-all clause looks like.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      FORALL-CLAUSE   ::=     'EVERY' BINDING-SET 'SATISFIES' BOOLEAN-EXPRESSION
2:      BINDING-SET             ::= VARIABLE 'IN' CONTENT</tt></pre>
</div></div>
<div class="paragraph"><p>In this context a binding set is used to define a variable binding for the specified variable given as literal starting with the prefix <em>$</em>. The keyword <em>IN</em> symbolize the relation between the variable and the sequence of values the variable could bind to which will be represented by the following <em>content</em> expression. The <em>content</em> expression can contain each query expression which creates a set of topic map constructs, like navigations. Normally the <em>content</em> expression only contains a simple navigation step using the <em>instances</em> axis.</p></div>
<div class="paragraph"><p>A for-all clause only returns <em>true</em> if each value of the content satisfies the condition defined by the contained boolean-expression. After the execution of the for-all clause the internal variable will be destroyed.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The complexity of quantified expression is much higher than simple expression because of the internal iteration over a varaible binding set.</td>
</tr></table>
</div>
<h5 id="_exists_clauses">Exists clauses</h5>
<div class="paragraph"><p>An <em>exists clause</em> can be split into numerically unrestricted and numerically restricted expression. Unrestricted exists clauses always starts with the keyword <em>SOME</em> followed by a binding-set and a boolean-expression similar to the <em>for-all caluse</em> as we see at the following query snippet.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      EXISTS-CLAUSE   ::=     'SOME' BINDING-SET 'SATISFIES' BOOLEAN-EXPRESSION
2:      BINDING-SET             ::= VARIABLE 'IN' CONTENT</tt></pre>
</div></div>
<div class="paragraph"><p>The expression returns <em>true</em> exactly if at least one variable binding of the binding set satisfies the contained boolean condition. If the boolean condition does not depends on new variables the binding-set can be removed. To avoid ambiguousness the keyword has to replace with the keyword <em>EXISTS</em>. The keyword can also be left out.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      EXISTS-CLAUSE   ::=     [ 'EXISTS' ] BOOLEAN-EXPRESSION</tt></pre>
</div></div>
<div class="paragraph"><p>Restricted exists clauses define an upper or lower bound of satisfying bindings.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      EXISTS-CLAUSE   ::=     'AT' ( 'LEAST' | 'MOST' ) NUMBER BINDING-SET 'SATISFIES' BOOLEAN-EXPRESSION
2:      BINDING-SET             ::= VARIABLE 'IN' CONTENT</tt></pre>
</div></div>
<div class="paragraph"><p>There are two syntactical forms of numerically restricted exists clauses. If the keyword <em>LEAST</em> is used the expression returns true if the condition will be satisfied by at least <em>n</em> items. The numerical bound of <em>n</em> will be represented by the <em>NUMBER</em> terminal. If the keyword <em>MOST</em> is used the expression returns true if the condition will be satisfied by at most <em>n</em> items.</p></div>
<h4 id="_boolean_operators">2.8.5. Boolean operators</h4>
<div class="paragraph"><p>To combine boolean primitves in the context of boolean condition the current draft supports <em>boolean expressions</em>. Boolean expressions normally representing a boolean conjunction, disjunction or negation. Sometimes they will be used to clamp a boolean combination to change the execution order.</p></div>
<div class="paragraph"><p>Boolean conjunctions are symbolized by the keyword <em>AND</em> and disjunction by the keyword <em>OR</em>. The keyword <em>NOT</em> is used to create a negation of a condition.</p></div>
<h3 id="_path_expression">2.9. Path expression</h3><div style="clear:left"></div>
<div class="paragraph"><p>The current draft of the topic maps query language supports three different types of query-expressions. Each of theme will be inspired by other query languages of other industrial standards. On of them is the path expression style inspired by the XPath language of XML documents.</p></div>
<div class="paragraph"><p>A path expression represent a set of navigations through the abstract bidirectional topic maps graph. To realize that the path-expression contains navigations as combination of the defined axes. By combine the navigation axes a path expression can be used to extract information of a topic map without complex conditions on the result set. In additon the results can be filtered by using an optional filter expression based on the boolean expressions. Currently the filter can only added at the end of the whole navigation and cannot be used after one step over a specific axis. This will be changed as soon as possible.</p></div>
<h4 id="_filter_expressions">2.9.1. Filter expressions</h4>
<div class="paragraph"><p>A filter expression is an optional part of path expressions to reduce the result set to a sub set of items matching the given filter definition. The concept is similar to filters of XPath expressions. A filter has to be added at the end of a path expression encapsulated by square brackets.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      FILTER-EXPRESSION ::= '[' BOOLEAN-EXPRESSION ']'</tt></pre>
</div></div>
<div class="paragraph"><p>The filter definition can contain each boolean expression discussed in the previous chapters of this document except the fact of missing variables bindings in the context of the path expression.</p></div>
<div class="paragraph"><p>In the context of a filter expression the dot <em>.</em> can be used to represent the items of the result set of the path expression. Using iterations each element of the navigation result will be bound to the dot <em>.</em> token representing the current node similar to the XPath notation.</p></div>
<div class="paragraph"><p>As frequently used filters the current draft defines a set of productions contained by the non-canonical level which can be used quite simple. A non-canonical filter can only used as stand-alone expression if the filter expression make use of conjunctions or disjunction the canonical counterpart has to be used.</p></div>
<h5 id="_type_filter">Type filter</h5>
<div class="paragraph"><p>A type filter simple removes all items which are not an instance of the defined type. The type can be defined as topic reference. The filter identified by the token <em>^</em> followed by the topic reference representing the topic type.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      [ ^ TOPIC-REF ]</tt></pre>
</div></div>
<div class="paragraph"><p>The productions is only valid on the non-canonical level. The canonical counterpart can be used in an equal way.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      [ . &gt;&gt; types == TOPIC-REF ]</tt></pre>
</div></div>
<div class="paragraph"><p>In contrast to the non-canonical type filter the canonical counterpart can be used in the context of boolean combinations.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut defined on the non-canonical level representing a type filter in a shorter way. The shortcut <em>//</em> can be used instead of <em>^</em> and the square brackets.</td>
</tr></table>
</div>
<h5 id="_index_filter">Index filter</h5>
<div class="paragraph"><p>If the user is only interested in a specific element at a defined index the index filter can be used to extract the element at the current position defined by a numerical literal. If the index is out of bound the constant topic <em>un-def</em> will be returned.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">By default topic maps and topic map items are unorded. The order of the contained items of the navigation result is quite haphazardly. Because of that the result of an index filter will be different for each execution.</td>
</tr></table>
</div>
<div class="paragraph"><p>A index filter simply represented by a numerical value. The canonical counterpart take use of a predefined variable of the query processor representing the current iteration index. The processor simple checks if the variable is bound to the same value than the user specified by the numerical literal.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      [ NUMBER ]                      #non-canonical production
2:
3:      [ $# == NUMBER ]        #canonical counterpart</tt></pre>
</div></div>
<h5 id="_index_range_filter">Index range filter</h5>
<div class="paragraph"><p>In addition to index filter the user can define an upper and lower border interpreted as a sub set of valid indexes. The processor will return each item with an index which is greater or equal to the lower bound but less than the upper bound.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The upper bound will be excluded everytime and all indices are zero based.</td>
</tr></table>
</div>
<div class="paragraph"><p>A index range filter simply represented by two numerical values and the special token <em>..</em>. The canonical counterpart take use of a predefined variable of the query processor representing the current iteration index. The processor simple checks if the variable is bound to a value contained by the defined range.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      [ NUMBER .. NUMBER ]                            #non-canonical production
2:
3:      [ NUMBER &gt;= $# AND NUMBER &lt; $# ]        #canonical counterpart</tt></pre>
</div></div>
<h5 id="_scope_filter">Scope filter</h5>
<div class="paragraph"><p>If the user is only interested in association items or characteristic items valid in a special scope, he can use the scope filter. A scope filter simply define a topic item representing one theme which has been included by the scope of the current node. If the current node is a topic item the filter fails everytime. The filter symbolized by the token <em>@</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      [ @ TOPIC-REF ]</tt></pre>
</div></div>
<div class="paragraph"><p>The productions is only valid on the non-canonical level. The canonical counterpart can be used in an equal way.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      [ . &gt;&gt; scope == TOPIC-REF ]</tt></pre>
</div></div>
<div class="paragraph"><p>In contrast to the non-canonical type filter the canonical counterpart can be used in the context of boolean combinations.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">There is a shortcut defined on the non-canonical level representing a cope filter in a shorter way and allow to remove the square brackets.</td>
</tr></table>
</div>
<h4 id="_projections">2.9.2. Projections</h4>
<div class="paragraph"><p>Mostly the user is interested in a number of different information items related to the same node of the abstract graph for example all names and all traversal topic players. To realize that the current draft supports projections which can be used instead of filter expressions. A projection used to combine the results of a set of navigations starting at the same node of the abstract graph.</p></div>
<div class="paragraph"><p>The projection is defined as a comma separated list of navigation expressions starting at the current node using the dot <em>.</em>. A projection can be add at the end of a navigation expression but cannot combine with a filter expression. In addition to that fact an projection must not contain filters as well.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      PROJECTION ::=  '(' &lt; VALUE-EXPRESSION &gt; ')'</tt></pre>
</div></div>
<div class="paragraph"><p>A projection definition is always encapsulated by round brackets. The definition of projections make use of value expressions containing simple navigation expressions but must not contain filter or projections as well. To define a number of projections they will be separated by a comma <em>,</em>.</p></div>
<h4 id="_tuple_expressions_as_path_expressions">2.9.3. Tuple expressions as path expressions</h4>
<div class="paragraph"><p>In addition to the simple navigation expressions a path expression can create a sequence of tuples containing more than one item using an expression type called <em>tuple expressions</em>. Tuple expressions are quite similar to projections because they based on the same production. The only difference is the missing navigation in front of the projection. A tuple expression is always encapsulated by round brackets and can contain a unrestricted number of navigations to extract multiple sets of navigation results. The dot <em>.</em> token cannot be used because of the missing context.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      TUPLE-EXPRESSION ::=    '(' &lt; VALUE-EXPRESSION &gt; ')'</tt></pre>
</div></div>
<div class="paragraph"><p>A tuple expression can be used to extract a set of topic items by using a comma-separated list of topic references.</p></div>
<div class="paragraph"><p>On the other hand the tuple expressions often used as parts of other productions like merge expressions.</p></div>
<h3 id="_select_expressions">2.10. Select expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>The current draft of the topic maps query language supports three different types of query-expressions. Each of theme will be inspired by other query languages of other industrial standards. One of them is the select-expression style inspired by the query language of relation databases - SQL.</p></div>
<div class="paragraph"><p>The select style represented by the production called <em>select expression</em>. A select expression contains a number of optional sub expression smilar to the SQL query language.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      select-expression       ::=     SELECT    &lt; value-expression &gt;
2:                                                      [  FROM   value-expression ]
3:                                                      [  WHERE   boolean-expression ]
4:                                                      [  ORDER BY    &lt; value-expression &gt; ]
5:                                                      [  UNIQUE  ]
6:                                                      [  OFFSET  value-expression ]
7:                                                      [  LIMIT  value-expression ]</tt></pre>
</div></div>
<div class="paragraph"><p>Only the slect-clause represented by the keyword <em>SELECT</em> is mandatory, all other expression can be left out.</p></div>
<h4 id="_processing_model">2.10.1. Processing model</h4>
<div class="paragraph"><p>The processing model of a select expression defines to execution order of the contained expressions. In this case the <em>from clause</em> has to be interpreted at first. The <em>from clause</em> define the context of possible variable bindings of the whole select expression and define a sub set of topic map constructs they can be bind to. If the <em>from clause</em> is missing the context will be defined as the whole queried topic map represented by the variable <em>%_</em>.</p></div>
<div class="paragraph"><p>After the execution of the <em>from clause</em> the offset and limit clause will be interpreted. The contained value expressions only define a numerical literal representing the first selected index and the maximum number of selected values. The result will be stored as the processing variables $_lower' and <em>$_limit</em>.</p></div>
<div class="paragraph"><p>Then all free unbound variables of the where-clause are determinded. Each variable are bound i. e. using iterations to any possible value of the context defined by the <em>from-clause</em>. During the processing of the where-clause each variable binding tuple will be checked for satisifaction in the context of the defined boolean condition. The result of the <em>where clause</em> will be a unordered sequence of tuple representing all satisfying variable bindings.</p></div>
<div class="paragraph"><p>If the <em>order-by clause</em> is used, the unordered sequence will be ordered using the defined value expressions.</p></div>
<div class="paragraph"><p>After the optional sortation of the variable bindings the <em>select clause</em> used to transform the variable bindings to the values to user is intersted in. The clause normally contains a set of navigations or functions to extract exactly the information the user is intersted in.</p></div>
<div class="paragraph"><p>The keyword <em>UNIQUE</em> only symbolize the reduction of the result set by removing duplicates. If the keyword is missing, the result set can contain each tuple multiple times.</p></div>
<div class="paragraph"><p>As last execution step the bounded variables <em>$_limit</em> and <em>$_lower</em> used to extract the expected selection window of the whole result set. To realize that the function <em>slice</em> is used.</p></div>
<h4 id="_select_clause">2.10.2. Select clause</h4>
<div class="paragraph"><p>The <em>select clause</em> is symbolized by the keyword <em>SELECT</em> and contains a comma-separated list of value expressions to transform the variable bindings of the evaluation to a sequence of tuples. Normally the <em>select clause</em> contains navigation expression or simple functions.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The select clause must not use variables which are not used in the context of the where-clause and they must not use anonymous variables like <em>$_</em> because the variables support only write-access.</td>
</tr></table>
</div>
<h4 id="_from_clause">2.10.3. From clause</h4>
<div class="paragraph"><p>The <em>from clause</em> is used to define the context of the query execution. The context is used to get the set of possible variable bindings used by the <em>where clause</em> to evalute variable bindings. The clause is optional if it is missing the context will be bound to the variable <em>%_</em> representing the queried topic map.</p></div>
<div class="paragraph"><p>Normally the clause contains a simple content combination or a navigation expression to define the context of the querying process for this select expression.</p></div>
<h4 id="_where_clause">2.10.4. Where clause</h4>
<div class="paragraph"><p>The <em>where clause</em> define a boolean condition to evalutate the variable bindings. The clause can contain every boolean expression which was discussed in the previous chapters. A where clause returns a set of satisfying variable bindings.</p></div>
<div class="paragraph"><p>The select expression can only use variable bound in the context of the where clause. If it is missing the usage of any variable is invalid.</p></div>
<h4 id="_order_by_clause">2.10.5. Order-by clause</h4>
<div class="paragraph"><p>The <em>order-by clause</em> is optional if it is missing the sequence of variable evalutations of the where clause keep unordered. The clause can be used to order them by using a comma-separated list of value expressions normally containing only simple navigations to get literals of internal characteristics of the bound items.</p></div>
<div class="paragraph"><p>The keywords <em>ASC</em> and <em>DESC</em> can be used after every value expression to define the order direction. If the keyword is missing <em>ASC</em> is used as default.</p></div>
<h4 id="_unique">2.10.6. Unique</h4>
<div class="paragraph"><p>By default the result set can contain the same tuple multiple times. Sometimes the user only interested in the unique set of results. By adding the keyword <em>UNIQUE</em> the result sequence will be reduced to a sequence containing every origin tuple only onetimes.</p></div>
<h4 id="_offset_clause">2.10.7. Offset clause</h4>
<div class="paragraph"><p>The offset clause is optional and starts witht the keyword <em>OFFSET</em> followed by a numerical literal. The numerical value will be bound to the system variable <em>$_lower</em> and will be used to define the first index of the result set to select. All tuples of the result sequence located at a lower index will be ignored and removed from the result set. If the clause is missing the offset will be <em>0</em>.</p></div>
<h4 id="_limit_clause">2.10.8. Limit clause</h4>
<div class="paragraph"><p>The limit clause is optional and starts with the keyword <em>LIMIT</em> followed by a numerical literal. The numerical value will be bound to the system variable <em>$_limit</em> and will be used as the maximum number of selected items. If the result set contains more than the limit clause restricts, they will be removed from the final result set. If the limit clause is missing the limit value will be <em>-1</em> representing an unlimited selection.</p></div>
<h3 id="_flwr_expressions">2.11. Flwr expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>The current draft of the topic maps query language supports three different types of query-expressions. Each of theme will be inspired by other query languages of other industrial standards. One of them is the flwr expression style inspired by programming languages or flwor of XML documents.</p></div>
<div class="paragraph"><p>The flwr style represented by the production called <em>flwr expression</em>. A flwr expression contains a number of optional sub expression smilar to a for loop of modern programming languages.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      flwr-expression ::=     [  FOR   variable-assignment ]
2:                                              [  WHERE   boolean-expression ]
3:                                              [  ORDER BY  &lt; value-expression &gt; ]
4:                                              RETURN   content</tt></pre>
</div></div>
<div class="paragraph"><p>Only the <em>return clause</em> represented by the keyword <em>RETURN</em> is mandatory.</p></div>
<h4 id="_processing_model_2">2.11.1. Processing model</h4>
<div class="paragraph"><p>At first the variable associations inside the <em>for clauses</em> will be evaluated in lexical order. Each <em>for clause</em> creates a sequences of variable bindings for a specific variable used as evaluation context for the variable in the context of the where clause. The overall result of all for clauses will be an unordered sequence of variable bindings.</p></div>
<div class="paragraph"><p>By adding the <em>order-by clause</em> the variables bindings can be ordered in the defined way. The order-by clause contains a set of value expressions defining the values used to order the variable bindings in the given context. The result will be a sequence of ordered variable bindings.</p></div>
<div class="paragraph"><p>All variable bindings will be evaluated by the boolean expression contained by the <em>where clause</em>. If the clause is missing all variables of the for clauses are interpreted as valid.</p></div>
<div class="paragraph"><p>After all the return clause is used iterative to extract the values by using the variables bindings. The return clause creates a tuple sequence by using the defined <em>content</em> expression and the variable binding set.</p></div>
<div class="paragraph"><p>The overall result can be a sequence of tuples containing topic map construct, CTM fragments or XML fragments.</p></div>
<h4 id="_for_clause">2.11.2. For clause</h4>
<div class="paragraph"><p>The <em>for clause</em> can be used to define a variable binding set of one specific variable. A flwr expression can contain any numbers of <em>for clauses</em> to create a set of variable bindings of a set of variables used in the context of the where clause.</p></div>
<div class="paragraph"><p>A <em>for clause</em> symbolized by the keywod <em>FOR</em> followed by a variable assignment for a specific variable. For more information using variables and variables bindings please take a look at the previous chapter.</p></div>
<h4 id="_where_clause_2">2.11.3. Where clause</h4>
<div class="paragraph"><p>The <em>where clause</em> define a boolean condition to evalutate the variable bindings. The clause can contain every boolean expression which was discussed in the previous chapters. A where clause returns a set of satisfying variable bindings.</p></div>
<div class="paragraph"><p>The retrun expression can only use variable bound in the context of the where clause or for clause. If both are missing the usage of any variable is invalid.</p></div>
<h4 id="_order_by_clause_2">2.11.4. Order-by clause</h4>
<div class="paragraph"><p>The <em>order-by clause</em> is optional if it is missing the sequence of variable evalutations of the where clause keep unordered. The clause can be used to order them by using a comma-separated list of value expressions normally containing only simple navigations to get literals of internal characteristics of the bound items.</p></div>
<div class="paragraph"><p>The keywords <em>ASC</em> and <em>DESC</em> can be used after every value expression to define the order direction. If the keyword is missing <em>ASC</em> is used as default.</p></div>
<h4 id="_return_clause">2.11.5. Return clause</h4>
<div class="paragraph"><p>The <em>return clause</em> is the only mandatory expression contained by the flwr style. The clause is used to transform the variable binding set evaluated by the where clause and for clauses to a sequence of tuples. Normally the return clause is used in an iterative way to transform each combination of valid variable bindings to a tuple sequence. All tuple sequences will be combined by using the combination operator <em>++</em>.</p></div>
<div class="paragraph"><p>The result of the <em>return clause</em> can be a sequence of different tuple types. Normally the tuple contain a set of topic map constructs represented as simple objects but the flwr style is the only expression style to return XML or CTM fragments too. By using special <em>content</em> expressions called <em>tm-conent</em> and <em>xml-content</em> the return clause will be create simple CTM or XML fragments.</p></div>
<h5 id="_return_xml_fragments">Return XML fragments</h5>
<div class="paragraph"><p>By using an <em>xml-content</em> expression inside the return clause the flwr expression will be return a sequence of XML fragments representing the result of the query.</p></div>
<div class="paragraph"><p>An <em>xml-content</em> simply represented by using XML-tags in the context of the return clause for example like the following one.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      RETURN &lt;xml&gt; Text &lt;/xml&gt;</tt></pre>
</div></div>
<div class="paragraph"><p>The interpretation of the XML content contained by the return clause depends on their type. XML-Tags and simple text will keep uninterpreted and will be add to the final XML fragment. All whitespace characters will be add in the same way.</p></div>
<div class="paragraph"><p>By using embeded queries the XML fragment can use the bounded variables of the <em>for clauses</em> and <em>where clause</em> or embed an independent sub-query. An embeded query expression symbolized by the enclosing angle brackets <em>{</em> and <em>}</em>. The content of this query expression can be represented by every expression type described by the whole draft like an other flwr expression or a path expression. At first the sub-query will be interpreted in the normal way except the dependency of inherit variable bindings by the enclosing expression, which means that the embeded query can use all variables bound by the enclosing expression, too.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The embeded query may not overwrite the inherit variables of the enclosing flwr expression.</td>
</tr></table>
</div>
<div class="paragraph"><p>The result of the embed query will be interpreted and added to the XML fragment. If the embed query returns any topic map construct it will be transformed to valid XML content using the XTM syntax. If the query returns literal values they will keep unmodified an will be added to the XML fragment as simple text content.</p></div>
<div class="paragraph"><p>Embed queries can be used at every position, like as a topic node &#8230;</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a sequence of XML fragments containing one XTM topic node for each person topic
2:      FOR $p IN // person
3:      RETURN &lt;xml&gt; { $p } &lt;/xml&gt;</tt></pre>
</div></div>
<div class="paragraph"><p>or as association node &#8230;</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a sequence of XML fragments containing one XTM association node for each played association of each person topic
2:      FOR $p IN // person
3:      RETURN &lt;xml&gt; { $p &lt;&lt; players } &lt;/xml&gt;</tt></pre>
</div></div>
<div class="paragraph"><p>or simple as text content &#8230;</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a sequence of XML fragments containing one XML node for each person topic containing the first name as text content
2:      FOR $p IN // person
3:      RETURN &lt;xml&gt; { $p / tm:name [0] } &lt;/xml&gt;</tt></pre>
</div></div>
<div class="paragraph"><p>or as attribute value.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a sequence of XML fragments containing one XML node using the first indicator of each person topic as value
2:      FOR $p IN // person
3:      RETURN &lt;person ref="{ $p &gt;&gt; indicators &gt;&gt; atomify [0] }" /&gt;</tt></pre>
</div></div>
<h5 id="_return_ctm_fragments">Return CTM fragments</h5>
<div class="paragraph"><p>By using an tm-content' expression inside the return clause the flwr expression will be return a sequence of CTM fragments representing the result of the query.</p></div>
<div class="paragraph"><p>The <em>tm-content</em> simply defined by the enclosing triple quotes symbolizing the CTM stream creating by the return clause.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      RETURN ''' Text '''</tt></pre>
</div></div>
<div class="paragraph"><p>The interpretation of the CTM content contained by the return clause depends on their type. Whitespaces and simple text will keep uninterpreted and will be add to the final CTM stream.</p></div>
<div class="paragraph"><p>By using embeded queries the CTM fragment can use the bounded variables of the <em>for clauses</em> and <em>where clause</em> or embed an independent sub-query. An embeded query expression symbolized by the enclosing angle brackets <em>{</em> and <em>}</em>. The content of this query expression can be represented by every expression type described by the whole draft like an other flwr expression or a path expression. At first the sub-query will be interpreted in the normal way except the dependency of inherit variable bindings by the enclosing expression, which means that the embeded query can use all variables bound by the enclosing expression, too.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The embeded query may not overwrite the inherit variables of the enclosing flwr expression.</td>
</tr></table>
</div>
<div class="paragraph"><p>The result of the embed query will be interpreted and added to the final CTM stream. If the embed query returns any topic map construct it will be transformed to valid CTM content using the CTM syntax. If the query returns literal values they will keep unmodified an will be added to the CTM stream as simple text content.</p></div>
<div class="paragraph"><p>Embed queries can be used at every position which expected topic map content, like as a topic &#8230;</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a sequence of CTM fragments containing one topic block for each person topic
2:      FOR $p IN // person
3:      RETURN ''' { $p } '''</tt></pre>
</div></div>
<div class="paragraph"><p>or as association items &#8230;</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a sequence of CTM fragments containing one association for each played association
2:      FOR $p IN // person
3:      RETURN ''' { $p &lt;&lt; players } '''</tt></pre>
</div></div>
<div class="paragraph"><p>or simple as a subject-identifier.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a sequence of CTM fragments containing one association definition using the indicator of each person topic
2:      FOR $p IN // person
3:      RETURN ''' life-in ( city : leipzig , person : { $p &gt;&gt; indicators &gt;&gt; atomify [0] } '''</tt></pre>
</div></div>
<h3 id="_insert_expressions">2.12. Insert expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>The part II of the topic maps query language specification contains the modification expressions of the language. The modification part supports four different expression types representing the four operation types modifying a topic map. Insert operation is one them and enables the creation of new topic map items. Insert operations are represented by <em>insert expressions</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      insert-expression ::= INSERT ''' ctm-stream ''' { WHERE query-expression }</tt></pre>
</div></div>
<div class="paragraph"><p>The only mandatory part of an <em>insert</em> expression is the <em>insert clause</em> symbolized by the keyword <em>INSERT</em>. The content which want to be added to the current topic map instance will be represented as CTM fragment similar to the CTM-stream of a <em>return clause</em>.</p></div>
<div class="paragraph"><p>It is possible to use embedded queries to create connections between existing content and the new items.</p></div>
<h4 id="_processing_model_3">2.12.1. Processing model</h4>
<div class="paragraph"><p>The processing model of insert expressions is quite simple. If there is an where clause it will be interpreted in the same way like as a part of a select expression or flwr expression. The where clause is used to evalute a sub set of possible variables bindings which should be used in the content of the insert clause. The result of the evalutation will be a set of variables bindings.</p></div>
<div class="paragraph"><p>Then the insert clause will be interpreted for each variable binding returned by the where-clause. If the CTM fragment contains an embedded query it will be interpreted and the result will be added to the CTM stream. If the result is an topic map information item it will be serialized to CTM. Literals will keep unmodified. Each variable binding creates one CTM fragment which will be deserialized to the corresponding topic map fragment and will be added to the queried topic map.</p></div>
<div class="paragraph"><p>The overall result of the query will be a singleton sequence of a singleton tuple containing the number of created items.</p></div>
<h4 id="_insert_clause">2.12.2. Insert clause</h4>
<div class="paragraph"><p>The insert clause only contains the keyword <em>INSERT</em> followed by a CTM stream enclosing by triple single quotes.</p></div>
<div class="paragraph"><p>By using embedded queries the CTM fragment can use the bounded variables of the <em>where clause</em> or embed an independent sub-query. An embedded query expression symbolized by the enclosing angle brackets <em>{</em> and <em>}</em>. The content of this query expression can be represented by every expression type described by the whole draft like an other flwr expression or a path expression. At first the sub-query will be interpreted in the normal way except the dependency of inherit variable bindings by the enclosing expression, which means that the embeded query can use all variables bound by the enclosing expression, too.</p></div>
<div class="paragraph"><p>If the <em>insert clause</em> creates an invalid CTM fragment in relation to the current CTM draft an error will be raised.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The embedded query may not overwrite the inherit variables of the enclosing flwr expression.</td>
</tr></table>
</div>
<div class="paragraph"><p>The result of the embed query will be interpreted and added to the final CTM stream. If the embed query returns any topic map construct it will be transformed to valid CTM content using the CTM syntax. If the query returns literal values they will keep unmodified an will be added to the CTM stream as simple text content.</p></div>
<div class="paragraph"><p>Embed queries can be used at every position which expected topic map content, like as a topic &#8230;</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a copy of each person topic
2:      INSERT ''' { $p } '''
3:      WHERE $p ISA person</tt></pre>
</div></div>
<div class="paragraph"><p>or as association items &#8230;</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # add a reification to the first association played by each person topic
2:      INSERT ''' { $p &lt;&lt; players } ~ reifier '''
3:      WHERE $p ISA person</tt></pre>
</div></div>
<div class="paragraph"><p>or simple as a subject-identifier.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # create a new association played by the each person topic
2:      INSERT ''' life-in ( city : leipzig , person : { $p &gt;&gt; indicators &gt;&gt; atomify [0] } '''
3:      WHERE $p ISA person</tt></pre>
</div></div>
<h4 id="_where_clause_3">2.12.3. Where clause</h4>
<div class="paragraph"><p>The <em>where clause</em> define a boolean condition to evaluate the variable bindings. The clause can contain every boolean expression which was discussed in the previous chapters. A where clause returns a set of satisfying variable bindings.</p></div>
<div class="paragraph"><p>The insert expression can only use variable bound in the context of the where clause. If it is missing the usage of any variable is invalid.</p></div>
<h3 id="_delete_expressions">2.13. Delete expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>The part II of the topic maps query language specification contains the modifcation expressions of the language. The modifcation part supports four different expression types representing the four operation types modifying a topic map. Delete operation is one them and enables the removage of specific elements of the topic map. Delete operations are represented by <em>delete expressions</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      delete-expression       ::= DELETE [ CASCADE ] &lt; value-expression &gt;
2:                                                      [ WHERE boolean-expression ]
3:
4:      delete-expression       ::= DELETE CASCADE ALL</tt></pre>
</div></div>
<div class="paragraph"><p>The only mandatory part of an <em>delete</em> expression is the <em>delete clause</em> symbolized by the keyword <em>DELETE</em> and a comma-separated list of value expressions. The keyword <em>CASCADE</em> is an optional part of the delete clause. In addition to the delete clause a where clause be used to evalutate a set of variable bindings similar to the insert expression.</p></div>
<div class="paragraph"><p>The value expressions of the delete clause are used to define exactly the information resources to delete like a locator object, an association item or a topic item.</p></div>
<h4 id="_processing_model_4">2.13.1. Processing model</h4>
<div class="paragraph"><p>The processing model of a delete expression is quite simple. If there is an where clause it will be interpreted in the same way like as a part of a select expression or flwr expression. The where clause is used to evalute a sub set of possible variables bindings which should be used in the content of the delete clause. The result of the evalutation will be a set of variables bindings.</p></div>
<div class="paragraph"><p>The delete clause will be execute for each valid variable binding of the where-clause. The delete clause contains a set of value expressions to define exactly the information resources to remove. Normally a value expression only define a variable to remove the bound value or use a navigation to navigate to the item to remove. The keyword <em>CASCADE</em> represents the deletion mode of the query processor. If the keyword is missing the processor only removes elements which are independent to other information resources of the same topic map. For example if a topic is used as theme, it cannot removed without using this keyword. If the keyword is contained every dependent item will be removed too.</p></div>
<div class="paragraph"><p>The overall result of the query will be a singleton sequence of a singleton tuple containing the number of removed items.</p></div>
<h4 id="_delete_clause">2.13.2. Delete clause</h4>
<div class="paragraph"><p>The <em>delete clause</em> starts with the keyword <em>DELETE</em> and is the only non-optional part of a delete expression. A delete clause contains a comma-separated list of value expressions used to identify exactly the information resources to remove. Normally a delete clause contains a list of variables or navigations based on variable bindings.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The delete clause can only contain variables which are bind by the where clause.</td>
</tr></table>
</div>
<div class="paragraph"><p>As addition to that the delete clause can contains a set of path expressions without any variables to remove specific items. For example if a specific topic has to be removed the delete clause only contains a topic reference of this topic item.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      # remove the topic representing the composer puccini
2:      DELETE http://psi.ontopedia.net/Puccini</tt></pre>
</div></div>
<h4 id="_cascade">2.13.3. Cascade</h4>
<div class="paragraph"><p>Sometimes information items cannot removed from a topic map because they are connected to other items in a way they must not simply removed. For example if a topic is used as a theme the meaning of a statment will be changed if the theme will be removed from the scope. The processor will stop the execution if at least one topic depends on other information resources.</p></div>
<div class="paragraph"><p>If the keyword <em>CASCADE</em> is used the processor will remove all dependent information items too. Please take care.</p></div>
<div class="paragraph"><p>If a topic item will be removed, the processor will remove all of its characterisic items and all played associations. If the deleted topic represent a topic type all instances and subtypes will be removed too. If the topic is a theme the scoped item will be removed too. If the topic item used as reifier the reification will be removed, but the reified item keep alive.</p></div>
<div class="paragraph"><p>If an association item will be removed the processor will remove all role constructs and destroy each scoping and reificiation relationship to any topic item.</p></div>
<div class="paragraph"><p>If a name item will be remove the processor will remove all variants too and destroy each scoping and reificiation relationship to any topic item.</p></div>
<div class="paragraph"><p>If a occurrence item will be removed the processor will destroy each scoping and reificiation relationship to any topic item.</p></div>
<div class="paragraph"><p>If a locator object will be removed the processor checks if the construct using the identifier has to remove too. The processor will remove the identified item too, if there isn&#8217;t another locator identifing the construct.</p></div>
<div class="paragraph"><p>If a variant item will be removed the processor will destroy each scoping and reificiation relationship to any topic item.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">The process is iterative which means i.e. if a name is removed because of the removage of its parent topic, all variants will be removed too.</td>
</tr></table>
</div>
<div class="paragraph"><p>The following table summarizes the dependencies resolved by the deletion processor.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="16%" />
<col width="83%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item type</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>removed dependencies</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">topic</p></td>
<td align="left" valign="top"><p class="table"><tt><tt></tt></tt><tt><tt></tt></tt>
<ul>
<li>all characterisitics and their dependencies</li>
<li>all association played</li>
<li>all instances ans subtypes</li>
<li>all scoped constructs using this item as theme</li>
<li>reification destroyed</li>
</ul>
<tt><tt></tt></tt><tt><tt></tt></tt></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">occurrence</p></td>
<td align="left" valign="top"><p class="table">reification destroyed</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">name</p></td>
<td align="left" valign="top"><p class="table"><tt><tt></tt></tt><tt><tt></tt></tt>
<ul>
<li>all variants</li>
<li>reification destroyed</li>
</ul>
<tt><tt></tt></tt><tt><tt></tt></tt></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">variant</p></td>
<td align="left" valign="top"><p class="table">reification destroyed</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">association item</p></td>
<td align="left" valign="top"><p class="table"><tt><tt></tt></tt><tt><tt></tt></tt>
<ul>
<li>all role constructs</li>
<li>reification destroyed</li>
</ul>
<tt><tt></tt></tt><tt><tt></tt></tt></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">a locator</p></td>
<td align="left" valign="top"><p class="table">the construct if there isn&#8217;t an other locator</p></td>
</tr>
</tbody>
</table>
</div>
<h4 id="_where_clause_4">2.13.4. Where clause</h4>
<div class="paragraph"><p>The <em>where clause</em> define a boolean condition to evalutate the variable bindings. The clause can contain every boolean expression which was discussed in the previous chapters. A where clause returns a set of satisfying variable bindings.</p></div>
<div class="paragraph"><p>The delete expression can only use variable bound in the context of the where clause. If it is missing the usage of any variable is invalid.</p></div>
<h4 id="_the_keyword_all">2.13.5. The keyword ALL</h4>
<div class="paragraph"><p>The keyword <em>ALL</em> can be used instead of a value-expression in the context of a delete-clause to remove all items of the queried topic map. The keyword <em>CASCADE</em> is mandatory.</p></div>
<h3 id="_merge_expressions">2.14. Merge expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>The part II of the topic maps query language specification contains the modifcation expressions of the language. The modifcation part supports four different expression types representing the four operation types modifying a topic map. Merge operation is one them and enables the controlled merging of topic map items. Merge operations are represented by <em>merge expressions</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      merge-expression ::= MERGE path-expression
2:
3:      merge-expression ::= MERGE &lt; value-expression &gt; WHERE boolean-expression
4:
5:      merge-expression ::= MERGE ALL WHERE boolean-expression</tt></pre>
</div></div>
<div class="paragraph"><p>There are three different grammatical productions of a merge-expression. Each merge expression starts with the symbolic keyword <em>MERGE</em> which will be used by the engine to indentify the expression type.</p></div>
<h4 id="_processing_model_5">2.14.1. Processing model</h4>
<div class="paragraph"><p>The processing model of a merge expression is quite simple. If there is an where clause it will be interpreted in the same way like as a part of a select expression or flwr expression. The where clause is used to evalute a sub set of possible variables bindings which should be used in the content of the delete clause. The result of the evalutation will be a set of variables bindings.</p></div>
<div class="paragraph"><p>The merge clause will be execute for each valid variable binding of the where-clause. The merge clause contains a set of value expressions or one path-expression to define exactly the information resources to merge. Normally a value expression only define a variable to remove the bound value or use a navigation to navigate to the item to remove. The keyword <em>ALL</em> can be used instead of contained expressions to indicates the merging process of all result items of the where-clause.</p></div>
<div class="paragraph"><p>The overall result of the query will be a singleton sequence of a singleton tuple containing the number of merged items.</p></div>
<h4 id="_merge_clause">2.14.2. Merge clause</h4>
<div class="paragraph"><p>The merge clause can contain a set of value expressions only containing variables which have to be bind by the where-clause. The second possibility is to add a path-expression defining the items to merge, in this case a where clause is not supported.</p></div>
<div class="paragraph"><p>All constructs will be merged according to the merging-rules of the TMDM.</p></div>
<h4 id="_where_clause_5">2.14.3. Where clause</h4>
<div class="paragraph"><p>The <em>where clause</em> define a boolean condition to evalutate the variable bindings. The clause can contain every boolean expression which was discussed in the previous chapters. A where clause returns a set of satisfying variable bindings.</p></div>
<div class="paragraph"><p>The merge expression can only use variable bound in the context of the where clause. If it is missing the usage of any variable is invalid.</p></div>
<h4 id="_the_keyword_all_2">2.14.4. The keyword ALL</h4>
<div class="paragraph"><p>The keyword <em>ALL</em> can be used instead of a value-expression in the context of a merge-clause to merge all items of the queried topic map. The keyword <em>CASCADE</em> is mandatory.</p></div>
<h3 id="_update_expressions">2.15. Update expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>The part II of the topic maps query language specification contains the modification expressions of the language. The modification part supports four different expression types representing the four operation types modifying a topic map. Update operation is one them and enables the modification of existing topic map items. Update operations are represented by <em>update expressions</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      update-expression       ::= UPDATE &lt; update-clause &gt; ( WHERE boolean-expression )
2:
3:      update-clause           ::= topic-def | predicate-invocation | anchor { topic-ref } ( SET | ADD ) value-expression</tt></pre>
</div></div>
<div class="paragraph"><p>An update-expression has to contain at least two sub-expressions, a where-clause and an update-clause. The number of update-clauses is not restricted but has to be greater than one.  The where-clause of an update-expression is used to define the context of changes done by the update-clauses. All update-clauses has to act in the same context and effect changes at the same topic map graph node. An update-clause can change a child-node of topic map item or add a new child-node to an existing topic map node.</p></div>
<h4 id="_processing_model_6">2.15.1. Processing model</h4>
<div class="paragraph"><p>The processing model of an update expression is quite simple. If there is an where clause it will be interpreted in the same way like as a part of a select expression or flwr expression. The where clause is used to evaluate a sub set of possible variables bindings which should be used in the content of the delete clause. The result of the evaluation will be a set of variables bindings.</p></div>
<div class="paragraph"><p>The update clause will be interpreted in the context defined by the where-clause. It contains exactly one atomic update statement for a topic map item which will be add a new child node or change the value of the child node.</p></div>
<div class="paragraph"><p>The overall result of the query will be a singleton sequence of a singleton tuple containing the number of changed and created items.</p></div>
<h4 id="_update_clause">2.15.2. Update clause</h4>
<div class="paragraph"><p>An update clause consists of an anchor identifier representing the type of child information which should be changed by the current expression. The following topic reference is optional and can be used for a specific number of anchors to define the type of the new child information. The keyword indicates the type of change as the creation of new child informations or the change of them. The value-expression at the end indicates the value which shall be set to the created or modified child node. The possible keywords are dependent from the given anchor and will be represented by the following matrix.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="10%" />
<col width="10%" />
<col width="10%" />
<col width="10%" />
<col width="10%" />
<col width="50%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>anchor</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>supported keyword</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>optional parameter</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>value-type</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>current node type</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>description</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">locators</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">any iri</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">adding a new subject-locator to given topic</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">indicators</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">any iri</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">adding a new subject-identifier to given topic</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">item</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">any iri</p></td>
<td align="left" valign="top"><p class="table">any item</p></td>
<td align="left" valign="top"><p class="table">adding a new item-identifier to given item</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">names</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">the name type</p></td>
<td align="left" valign="top"><p class="table">any string</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">adding a new name to given topic. If the name-type is empty, then "default-name-type":http://www.isotopicmaps.org/sam/sam-model/#d0e2429 of TMDM is used</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"></p></td>
<td align="left" valign="top"><p class="table">SET</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">any string</p></td>
<td align="left" valign="top"><p class="table">a name</p></td>
<td align="left" valign="top"><p class="table">setting the value of the given name</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">occurrences</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">the occurrence type</p></td>
<td align="left" valign="top"><p class="table">any object</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">adding a new occurrences to given topic. If the occurrence-type is empty, then occurrence-type of TMDM is used (<a href="http://psi.topicmaps.org/iso13250/glossary/occurrence-type">http://psi.topicmaps.org/iso13250/glossary/occurrence-type</a>)</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"></p></td>
<td align="left" valign="top"><p class="table">SET</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">any object</p></td>
<td align="left" valign="top"><p class="table">an occurrence</p></td>
<td align="left" valign="top"><p class="table">setting the value of the given occurrence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">scope</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">an association, a name or an occurrence</p></td>
<td align="left" valign="top"><p class="table">adding a new theme to the scope of the given item</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">types</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">a topic or an iri</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">adding a new type to the given topic, if type does not exists and value is an iri, the type will be created</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"></p></td>
<td align="left" valign="top"><p class="table">SET</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">a topic or an iri</p></td>
<td align="left" valign="top"><p class="table">an association, a name or an occurrence</p></td>
<td align="left" valign="top"><p class="table">setting the type to the given topic, if type does not exists and value is an iri, the type will be created</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">instances</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">a topic or an iri</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">adding a new instance to the given type, if instance does not exists and value is an iri, the instance will be created</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">supertypes</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">a topic or an iri</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">adding a new supertype to the given topic, if supertype does not exists and value is an iri, the supertype will be created</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">subtypes</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">a topic or an iri</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">adding a new subtype to the given topic, if subtype does not exists and value is an iri, the subtype will be created</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">players</p></td>
<td align="left" valign="top"><p class="table">SET</p></td>
<td align="left" valign="top"><p class="table">the role type</p></td>
<td align="left" valign="top"><p class="table">a topic or an iri</p></td>
<td align="left" valign="top"><p class="table">a topic</p></td>
<td align="left" valign="top"><p class="table">setting the player of all or the given role, if player does not exists and value is an iri, the player will be created</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">roles</p></td>
<td align="left" valign="top"><p class="table">ADD</p></td>
<td align="left" valign="top"><p class="table">the player</p></td>
<td align="left" valign="top"><p class="table">a topic or an iri</p></td>
<td align="left" valign="top"><p class="table">an association</p></td>
<td align="left" valign="top"><p class="table">adding a new role-player combination to the given association, if role-type does not exists and value is an iri, the role-type  will be created. If player is empty the tm:subject is used</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">reifier</p></td>
<td align="left" valign="top"><p class="table">SET</p></td>
<td align="left" valign="top"><p class="table">not supported</p></td>
<td align="left" valign="top"><p class="table">a topic, an association, a name or an occurrence</p></td>
<td align="left" valign="top"><p class="table">a topic, an association, a name or an occurrence</p></td>
<td align="left" valign="top"><p class="table">Setting a new reification. <strong>Hint:</strong> Restrictions of TMDM are checked</p></td>
</tr>
</tbody>
</table>
</div>
<h5 id="_topic_definition">Topic Definition</h5>
<div class="paragraph"><p>A topic definition can be used to define a new topic item by one of its identities. A topic can be created by using a string literal as item-identifier, subject-identifier or subject-locator. The type of identity is specified by the navigation pattern behind the string reference. If there is no navigation pattern, the default is subject-identifier. The identity type can also be defined by the non-canonical shortcut of the corresponding navigation axis.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      topic-def       ::=     string ( '&lt;&lt;' 'indicators' | '~' )? # by subject-identifier
2:
3:      topic-def       ::=     string ( '&lt;&lt;' 'item' | '!' ) # by item-identifier
4:
5:      topic-def       ::=     string ( '&lt;&lt;' 'locators' | '=') ) # by subject-locator</tt></pre>
</div></div>
<h5 id="_association_definition">Association Definition</h5>
<div class="paragraph"><p>An association definition is similar to a predicate invocation and can be used to create a new association in the context of the current topic map. The syntax is similar to predicate-invocation except the usage of ellipsis is not allowed.</p></div>
<h4 id="_where_clause_6">2.15.3. Where clause</h4>
<div class="paragraph"><p>The <em>where clause</em> define a boolean condition to evaluate the variable bindings. The clause can contain every boolean expression which was discussed in the previous chapters. A where clause returns a set of satisfying variable bindings.</p></div>
<div class="paragraph"><p>The update expression can only use variable bound in the context of the where clause. If it is missing the usage of any variable is invalid.</p></div>
</div>
<h2 id="_tmql4j">3. TMQL4J</h2>
<div class="sectionbody">
<div class="paragraph"><p>The tmql4j engine is the first Java-based engine processing the topic maps query language. The engine id designed as processing chain of independent modules and in a flexible architecture to provide the possibility of integrating your own module extensions and adaptations. The engine supports the draft of the 15th of august 2008 in addition to a number of extension like the topic maps modification language ( TMQL-ML ), the topic maps transaction language ( TMQL-TL ) and the topic maps inspection language ( TMQL-IL ).</p></div>
<h3 id="_design_patterns">3.1. Design patterns</h3><div style="clear:left"></div>
<h4 id="_architecture">3.1.1. Architecture</h4>
<div class="paragraph"><p>The TMQL4J engine offers a new abstraction layer on top of the TMAPI. Instead of accessing the Topic Maps engine directly applications may use a simple TMQL query. The architecture of Topic Maps applications is layered. The base of all applications are the Topic Maps backends, which are administrated by the Topic Maps engines. To abstract from the real implementation, TMAPI is used as a standardized interface. The last layer under the application is the TMQL4J engine.</p></div>
<h4 id="_modularization">3.1.2. Modularization</h4>
<div class="paragraph"><p>TMQL4J is designed as a multi-lingual querying engine providing different TMQL versions or other topic map query languages like tolog. As base modules of version 3.0.0 the engine supports the TMQL drafts of 2007 and 2010.</p></div>
<div class="paragraph"><p>Each style of the query language are encapsulated by its own plug-in which can be added to the class-path if needed. If a plug-in is missing, the parser and lexical scanner does not supports this style.</p></div>
<h4 id="_optimization">3.1.3. Optimization</h4>
<div class="paragraph"><p>TMQL4J realizes an additional abstraction layer over the TMAPI and implements additional features to speed up the querying process by using new index implementations and extension of the TMAPI.</p></div>
<h4 id="_omnigator_plug_in">3.1.4. Omnigator Plug-in</h4>
<div class="paragraph"><p>As one of the first implementations, we provide a generic query plug-in for the Topic Maps browser Omnigator, called tmql4ontopia. It offers the possibility to query the Topic Maps using the TMQL syntax. The generic plug-in is an extension of TMQL4J</p></div>
<h3 id="_create_the_runtime">3.2. Create the Runtime</h3><div style="clear:left"></div>
<div class="paragraph"><p>The whole querying process is encapsulated by a container called runtime. The runtime provides methods to define prefixes or register new functions or any other extensions..</p></div>
<div class="paragraph"><p>The runtime can not be instantiate in a usual way. The user has to use an instance of the runtime factory to get an representation of this container class using the topic map system as optional argument. The container implementation is represented by an interface class to hide internal methods and unify the using of the engine. The next paragraphs describing each function provided by the runtime interface and how it shall be used to realize the business use cases.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      TopicMapSystem topicMapSystem = TopicMapSystemFactory.newInstance().newTopicMapSystem();
2:
3:      TopicMap topicMap = topicMapSystem.createTopicMap("http://de.topicmapslab/tmql4j/");
4:
5:      File ltm = new File("src/test/resources/ItalianOpera.ltm");
6:
7:      LTMTopicMapReader reader = new LTMTopicMapReader(topicMap, ltm);
8:      reader.read();
9:
10:     ITMQLRuntime runtime = TMQLRuntimeFactory.newFactory().newRuntime();
11:
12:     IQuery query = runtime.run(topicMap, "http://psi.ontopedia.net/Puccini");</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The short code snippet give you an overview about initializing and using the runtime container. As we can see in line 10, the <em>TMQLRuntimeFactory</em> is used to create a new runtime by calling the method <em>newRuntime</em>. In the lines 1 until 8 we initializing the topic map instance by importing a topic map from an external LTM file. The last code line of the snippet calling the runtime to execute the given query.</p></div>
</div></div>
<div class="paragraph"><p>The factory supports a set of different method initializing a runtime container estimating a topic map system and/or the language name which should be supported by the runtime instance.</p></div>
<h4 id="allowed_expressions">3.2.1. Control supported expressions</h4>
<div class="paragraph"><p>Using a query instance the application can control the parsing process by excluding forbidden expression types, like the insert - or update-expressions. The query only handle forbidden expression, any other expression are allowed. If a query contains a restricted expression type an exception will be thrown by the parser implementation. Please note that the expression types only represent restriction of first-level expressions, that means that the expression only restricted as children of the root expression containing in the generated parsing tree. If the expression is used in lower levels of the tree it wont be restricted and wont be affected in an exception.</p></div>
<div class="paragraph"><p>As a special shortcut the query interface provides the functionality to disable all expression types which occurs a modification of the topic map as one call.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      IQuery query = new TMQLQuery(topicMap, "INSERT \"\"\" myTopic . \"\"\"");
2:      query.forbidExpression(InsertExpression.class);
3:
4:      query.forbidModificationQueries();</tt></pre>
</div></div>
<h3 id="_query">3.3. Query</h3><div style="clear:left"></div>
<div class="paragraph"><p>A query using in context of the runtime container can represented in two different ways, as string literal or as instance of a class implementing the <em>IQuery</em> interface. If the query is represented as string-literal the runtime container auTomatically create a new instance of IQuery representing the given string-literal using the <em>QueryFactory</em> of the engine.</p></div>
<h4 id="_query_factory">3.3.1. Query-Factory</h4>
<div class="paragraph"><p>Currently there is no industrial standard of a topic maps query language, but it is fundamental for each business application to extract the information used to resolve the use cases in a easy way. Because of that and the missing standard there are many languages realizing a query language of topic maps at the moment - TOLOG, Toma, TMQL and a topic maps path language. Many applications using topic maps are based on one of this query languages but can not handle any other of them. The tmql4j provides the functionality to convert any other query format to a topic maps query language pattern ( TMQL ). A developer can use a simple interface to add a new query transformer module to the core implementation of the tmql4j engine and can use his language, like SQL, to query a topic map.</p></div>
<div class="paragraph"><p>Because of the different syntactical notification of each language it is not secure to instantiate a query by using a specific IQuery implementation class, except the user can be sure that the given literal is valid in context of the represented query language. Instead of initializing the query the query factory shall be used to create a query from a given string-literal. The query factory try to detect the query language the given string-literal is written in and create a new instance of this query class. Because of the fact that the tmql4j engine only handles real TMQL queries the <em>toTMQL</em> method will be called by the query factory to transform the specific query to a TMQL query. A developer has to provide the transformation functionality to use his own query language with the tmql4j engine.</p></div>
<h4 id="_tolog2tmql_plugin">3.3.2. TOLOG2tmql PlugIn</h4>
<div class="paragraph"><p>The TOLOG2tmql plugin implementing a query transformer for the query language TOLOG, which was established as de-facto standard as a part of the Ontopia topic maps engine. Some parts of the current draft inspired by the TOLOG query language. In combination with the plugin the tmql4j engine can used with TOLOG queries. Please note that the current version of the TOLOG2tmql plugin only supports the querying part of the TOLOG query language and not the additional modification part developed in 2009. The next version of the plugin will be support the whole TOLOG specification.</p></div>
<div class="paragraph"><p><strong>Please note:</strong> This sub-project is still not open source. If you are interested in please contact the project owner.</p></div>
<h4 id="_tmpl2tmql_plugin">3.3.3. tmpl2tmql PlugIn</h4>
<div class="paragraph"><p>The second query plugin supported by the topic maps query language engine tmql4j is called tmpl2tmql. The plugin implements a query transformer for a query language similar to the XPath style and only containing path expressions to navigate through the abstract topic maps graph to extract all informations need for the use case. Because of the fact that the topic maps path language ( TMPL ) is not a standard and will be changed permanently, the plugin version can be out of date of a specific version, but we try to be up to date as soon as possible.</p></div>
<div class="paragraph"><p><strong>Please note:</strong> This sub-project is still not open source. If you are interested in please contact the project owner.</p></div>
<h4 id="_toma2tmql_plugin">3.3.4. Toma2tmql PlugIn</h4>
<div class="paragraph"><p>Another query language for topic maps developed as alternative for the current topic maps query language part called Toma. The syntax of Toma is similar to an object-oriented programming language and was also inspired by the query language SQL of relation databases. The Toma2tmql plugin provides the functionality to use Toma queries to query a topic map using the tmql4j engine. Similar to the other plugins, it contains a query transformer to translate Toma queries to TMQL queries.</p></div>
<div class="paragraph"><p><strong>Please note:</strong> This sub-project is still not open source. If you are interested in please contact the project owner.</p></div>
<h4 id="_integrate_your_own_query_language_plug_in">3.3.5. Integrate your own query language plug-in</h4>
<div class="paragraph"><p>The tmql4j engine can be extended by own query language plugins to integrate your own query language in the tmql4j engine. The new plugin has to contain at least one class implements the <em>IQuery</em> interface of the tmql4j engine. In addition the tmql4j engine contains an abstract base implementation of <em>IQuery</em> implementing the base functions of this interface. The abstract base class can be use to reduce the implementation work.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public class MyQueryImplementation extends QueryImpl {
2:      ...
3:      }</tt></pre>
</div></div>
<h3 id="_prefix_definitions">3.4. Prefix Definitions</h3><div style="clear:left"></div>
<div class="paragraph"><p>In the context of a TMQL query a topic will be represented by a subject-identifier, subject-locator or item-identifier. Each of this identifiers are represented by a string-represented IRI which has to be known by the underlying topic maps engine. Related to a model, the most identifiers of a topic map will be similar to each other in relation to their IRI string literals, except from a short part at the end of the IRI literal. The identifiers use the same prefix and because of using a set of topics as part of the query we have to write a set of many identifiers only differs in a short part at the end. The solution of this problem is to define a number of prefixes and use relative IRIs instead of the absolute one.</p></div>
<div class="paragraph"><p>There are some predefined prefixes defined by the current draft of the topic maps query language which can be used without defining explicitly. The following prefixes are contained by the predefined environment.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="12%" />
<col width="25%" />
<col width="62%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>prefix literal</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>absolute IRI</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>description</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tm</p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/iso13250/model/">http://psi.topicmaps.org/iso13250/model/</a></p></td>
<td align="left" valign="top"><p class="table">This is the namespace for the concepts defined by TMDM (via the TMDM/TMRM mapping).</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">xsd</p></td>
<td align="left" valign="top"><p class="table"><a href="http://www.w3.org/2001/XMLSchema">http://www.w3.org/2001/XMLSchema</a>#</p></td>
<td align="left" valign="top"><p class="table">This is the namespace for the XML Schema Datatypes.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">tmql</p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/">http://psi.topicmaps.org/tmql/1.0/</a></p></td>
<td align="left" valign="top"><p class="table">Under this prefix the concepts of TMQL itself are located.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">fn</p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/">http://psi.topicmaps.org/tmql/1.0/functions/</a></p></td>
<td align="left" valign="top"><p class="table">Under this prefix user-callable functions of the predefined TMQL environment are located.</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">dc</p></td>
<td align="left" valign="top"><p class="table"><a href="http://purl.org/dc/terms/">http://purl.org/dc/terms/</a></p></td>
<td align="left" valign="top"><p class="table">Under this prefix Dublin Core elements are located.</p></td>
</tr>
</tbody>
</table>
</div>
<h4 id="_define_prefixes_as_query_part">3.4.1. Define Prefixes as Query-Part</h4>
<div class="paragraph"><p>The current draft of the query language define an special expression type to define prefixes as part of the query itself. The defined prefixes are only valid for this specific query and not for the whole runtime. If the user wants to define a prefix only for a query this method should be used. The number of prefixes defined as part of the query is not restricted by the current draft. The prefix definition is a part of the environment clause of a TMQL query and starts with the keyword <em>%prefix</em> followed by the prefix literal and the absolute IRI as replacement of the prefix IRI.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix tmql4j http://tmql4j.topicmapslab.de/</tt></pre>
</div></div>
<div class="paragraph"><p>The defined prefixes can be used as QNames as part of a relative IRI in the context of the same query to identify a topic or a topic type.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix tmql4j http://tmql4j.topicmapslab.de/ tmql4j:person &gt;&gt; instances
2:
3:      http://tmql4j.topicmapslab.de/person &gt;&gt; instances</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The example show two queries with the same meaning. In line 1 there is a query using prefix definitions as part of the environment clause and uses the defined prefix literal as QName of the identifier <em>tmql4j:person</em>. As we can see the QName and the rest of the IRI will be devide by a colon. The second query in line 3 don&#8217;t use a prefix definition, but in the current example it is shorter because the prefix is used only one times. Please note that the benefits of using prefixes is proportional to the number of repeating IRI parts.</p></div>
</div></div>
<h4 id="_define_prefixes_using_properties">3.4.2. Define Prefixes using Properties</h4>
<div class="paragraph"><p>Sometimes a prefix will be used in different queries by the same tmql4j engine, so it will be uncomfortable to define this prefixes as part of each query again. The tmql4j engine provides a method to register additional prefixes which are valid in the whole runtime lifecycle. The method expects two arguments which are the same like the tokens of the prefix definition as a part of the query. The first argument is the prefix literal and the second is the absolute IRI represented by the QName.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      PrefixHandler handler = runtime.getLanguageContext().getPrefixHandler();
2:
3:      property.registerPrefix("tmql4j", "http://tmql4j.topicmapslab.de");</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The prefix management will be encapsulate by the language context which can be accessed by the runtime method <em>getLanguageExtension</em> as we can see in line 1. In line 3 the method <em>registerPrefix</em> of the prefix handler will be used to add a new prefix definition to the runtime container with the prefix literal <em>tmql4j</em> and the given string-represented IRI. The code line 3 has the same effect like the prefix definition of the last section, but in addition each query executed by the runtime container can use the prefix without defining it as a part of the query.</p></div>
</div></div>
<h3 id="_functions">3.5. Functions</h3><div style="clear:left"></div>
<div class="paragraph"><p>Similar to the other query languages like SQL, the current draft specify a number of functions which can be used to transform tuples or sequences. Each function are represented by a topic as a part of the environment topic map of the runtime container and can be used as part of the TMQL query like each other topic reference. In addition TMQL define a expression type called <em>function-invocation</em> to call a function with a list of arguments. Each function will be addressed by a topic item reference and a tuple-expression to define the parameter list given to the function interpreter.</p></div>
<div class="paragraph"><p>Each function type will be handled by a special function interpreter module.</p></div>
<h4 id="_predefined_functions">3.5.1. Predefined functions</h4>
<div class="paragraph"><p>The current draft of TMQL contains a number of predefined functions which are implemented by the tmql4j engine and can be used as a part of the given query.</p></div>
<h5 id="_string_concat_2">string concat</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-concat">http://psi.topicmaps.org/tmql/1.0/functions/string-concat</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table"><br /></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-concat (a : string, b : string) return string</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">2</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-concat</em> combines a set of strings. The function expects exactly two arguments given by the following tuple-expression. The type of the argument can be simple strings or sets of strings and the result will be a set of strings or a simple string. The behaviour of the function is dependent from the given argument type. If the first argument <em>a</em> is a string and the second argument <em>b</em> two, the method will return the string combination of <em>a</em> and <em>b</em>. If one of the arguments <em>a</em> or <em>b</em> is a set of strings the method will return a set of strings containing each combination of the atomic string and each string of the given set. If both arguments are sets the method will return each combination of each string of the first set and the second set.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-concat ( a =&gt; [ "foo" ] , b =&gt; [ "bar" ] )
2:      =&gt; "foobar"
3:
4:      fn:string-concat ( a =&gt; [ "foo" , "main" ] , b =&gt; [ "bar" ] )
5:      =&gt; [ "foobar" , "mainbar" ]
6:
7:      fn:string-concat ( a =&gt; [ "foo" , "main" ] , b =&gt; [ "bar" , "menu" ] )
8:      =&gt; [ "foobar" , "mainbar" , "foomenu" , "mainmenu" ]</tt></pre>
</div></div>
<h5 id="_string_length_2">string-length</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-length">http://psi.topicmaps.org/tmql/1.0/functions/string-length</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:length (s : string) return integer</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>length</em> returns the internal size of a string literal by counting the contained characters. The function expect exactly one argument which can be a simple string or a sequence of strings. The behaviour of the function is dependent from the given argument type. If the argument is a simple string the function return a single integer value. If the argument is a set of strings it will return a sequence of integer values.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:length ( s =&gt; [ "foo" ]  )
2:      =&gt; 3
3:
4:      fn:length ( s =&gt; [ "foo" , "main" ] )
5:      =&gt; [ 3 , 4 ]</tt></pre>
</div></div>
<h5 id="_string_less_than_2">string-less-than</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-less-than">http://psi.topicmaps.org/tmql/1.0/functions/string-less-than</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&lt;</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-lt (a : string, b : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-lt</em> compare the two string literals and only return the string literal given by the first argument if the literal is lexicographically lower than the second string. The function expected two arguments which has be of the type string. The first argument also can be a sequence of strings. The behaviour of the function is dependent from the given argument type. If the first argument is a set of strings the function returns a set containing the lexicographically lower string in relation to the second string argument. If the first argument is a string it return the given string if it is lexicographically lower than the second one, otherwise it return an empty set. If the second argument is a set of strings the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-lt ( a =&gt; [ "a" ] , b =&gt; [ "aaa" ] )
2:      =&gt; "a"
3:
4:      fn:string-lt ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" ] )
5:      =&gt; "a"
6:
7:      fn:string-lt ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" , "bbb" ] )
8:      =&gt; "a"</tt></pre>
</div></div>
<h5 id="_string_less_equal_than_2">string-less-equal-than</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-less-equal-than">http://psi.topicmaps.org/tmql/1.0/functions/string-less-equal-than</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&lt; =</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-leq (a : string, b : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-leq</em> compare the two string literals and only return the string literal given by the first argument if the literal is lexicographically lower or equal than the second string. The function expected two arguments which has be of the type string. The first argument also can be a sequence of strings. The behaviour of the function is dependent from the given argument type. If the first argument is a set of strings the function returns a set containing the lexicographically lower string in relation to the second string argument. If the first argument is a string it return the given string if it is lexicographically lower or equal than the second one, otherwise it return an empty set. If the second argument is a set of strings the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-leq ( a =&gt; [ "a" ] , b =&gt; [ "aaa" ] )
2:      =&gt; "a"
3:
4:      fn:string-leq ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" ] )
5:      =&gt; "a"
6:
7:      fn:string-leq ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" , "bbb" ] )
8:      =&gt; "a"</tt></pre>
</div></div>
<h5 id="_string_greater_equal_than_2">string-greater-equal-than</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-greater-equal-than">http://psi.topicmaps.org/tmql/1.0/functions/string-greater-equal-than</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&gt;=</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-geq (a : string, b : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-geq</em> compare the two string literals and only return the string literal given by the first argument if the literal is lexicographically greater or equal than the second string. The function expected two arguments which has be of the type string. The first argument also can be a sequence of strings. The behaviour of the function is dependent from the given argument type. If the first argument is a set of strings the function returns a set containing the lexicographically greater string in relation to the second string argument. If the first argument is a string it return the given string if it is lexicographically greater or equal than the second one, otherwise it return an empty set. If the second argument is a set of strings the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-geq ( a =&gt; [ "a" ] , b =&gt; [ "aaa" ] )
2:      =&gt; [ ]
3:
4:      fn:string-geq ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" ] )
5:      =&gt; "b"
6:
7:      fn:string-geq ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" , "bbb" ] )
8:      =&gt; "b"</tt></pre>
</div></div>
<h5 id="_string_greater_than_2">string-greater-than</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-greater-than">http://psi.topicmaps.org/tmql/1.0/functions/string-greater-than</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&gt;</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:string-gt (a : string, b : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>string-gt</em> compare the two string literals and only return the string literal given by the first argument if the literal is lexicographically greater than the second string. The function expected two arguments which has be of the type string. The first argument also can be a sequence of strings. The behaviour of the function is dependent from the given argument type. If the first argument is a set of strings the function returns a set containing the lexicographically greater string in relation to the second string argument. If the first argument is a string it return the given string if it is lexicographically greater than the second one, otherwise it return an empty set. If the second argument is a set of strings the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:string-gt ( a =&gt; [ "a" ] , b =&gt; [ "aaa" ] )
2:      =&gt; [ ]
3:
4:      fn:string-gt ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" ] )
5:      =&gt; "b"
6:
7:      fn:string-gt ( a =&gt; [ "a" , "b" ] , b =&gt; [ "aaa" , "bbb" ] )
8:      =&gt; "b"</tt></pre>
</div></div>
<h5 id="_string_regexp_match_2">string-regexp-match</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/string-regexp-match">http://psi.topicmaps.org/tmql/1.0/functions/string-regexp-match</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">=~</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:regexp (s : string, re : string) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>regexp</em> checks if the given string argument matches to the regular expression. The method expected exactly two arguments, which can be an instance of string or a simple sequence or strings. The behaviour of the function is dependent from the given argument type. If the first argument is a simple string, the result will be an empty sequence if the string does not match or the string if it matches. If the first argument is a set of strings the function will return a set of all matching strings. If the second argument is a set of strings only the first one will be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:regexp ( a =&gt; [ "aaa" ] , b =&gt; [ "[a]+" ] )
2:      =&gt; "aaa"
3:
4:      fn:regexp ( a =&gt; [ "aaa" , "bbb" ] , b =&gt; [ "[a]+" ] )
5:      =&gt; "aaa"
6:
7:      fn:regexp ( a =&gt; [ "aaa" , "bbb" ] , b =&gt; [ "[a]+" , "[b]+" ] )
8:      =&gt; "aaa"</tt></pre>
</div></div>
<h5 id="_substring_2">substring</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/substring">http://psi.topicmaps.org/tmql/1.0/functions/substring</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:substring (s : string, f : interger , t : interger ) return string</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">5</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>substring</em> will be return an substring of the given string argument addressed by the given indexes. The function expects exactly three arguments of type string and integer. As first argument a string sequence is supported two. The behaviour of the function is dependent from the given arguments. If the first argument is a string it will return a single string representing the substring of the first argument. If the first argument is a sequence it will return a sequence of substrings. If any of the indexes is out of bounds the function will clear this indexes to the possible values which are encapsulate by the given range. The string indexes will be zero-based and the upper index will be excluded.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:substring ( s =&gt; [ "Java-based engine" ] , f =&gt; 1 , t =&gt; 5 )
2:      =&gt; "ava-"
3:
4:      fn:substring ( s =&gt; [ "Java-based engine" , "foo" ] , f =&gt; 1 , t =&gt; 5 )
5:      =&gt; [ "ava-" , "oo" ]
6:
7:      fn:substring ( s =&gt; [ "Java-based engine" , "foo" ] , f =&gt; -1 , t =&gt; 50 )
8:      =&gt;  [ "Java-based engine" , "foo" ]
9:
10:     fn:substring ( s =&gt; [ "Java-based engine" , "foo" ] , f =&gt; "1" , t =&gt; "5" )
11:     =&gt;  [ "ava-" , "oo" ]
12:
13:     fn:substring ( s =&gt; [ "Java-based engine" , "foo" ] , f =&gt; "a" , t =&gt; "5" )
14:     =&gt;  raises an error</tt></pre>
</div></div>
<h5 id="_has_datatype_2">has-datatype</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/has-datatype">http://psi.topicmaps.org/tmql/1.0/functions/has-datatype</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:has-datatype (s: tuple-sequence) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>has-datatype</em> retrieves the data type for each tuple element in each tuple. The function expects exactly one argument which has to be a tuple or a tuple sequence. The behaviour of the functions is dependent from the given arguments. If the the contained element is a name item the data type will be <em>string</em>, for occurrence item  it will be the internal data type and for each atom it will be the data type of the atom itself. Any other item results in the data type <em>any</em>. Each data type is a IRI.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:has-datatype ( s =&gt; [ "http://tmql4j.topicmapslab.de"^^xsd:anyURI , "aaa" , 5 ] )
2:      =&gt;  [ "xsd:anyURI" , "xsd:string" , "xsd:interger" ]</tt></pre>
</div></div>
<h5 id="_has_variant_2">has-variant</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/has-variant">http://psi.topicmaps.org/tmql/1.0/functions/has-variant</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:has-variant (s: tuple-sequence, s: item-reference) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function has-variant only supported for topic name items. The function expected exactly two argument which has to be a tuple sequence and a topic reference. It retrieves the variant items for each tuple element in each tuple the variant name for the given scope. For name items this is the variant value, if such exists. Otherwise it is undef. For all other things the function will return ever undef.</p></div>
<h5 id="_slice_2">slice</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/slice">http://psi.topicmaps.org/tmql/1.0/functions/slice</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:slice (s : tuple-sequence, low : integer, high : integer) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>slice</em> is a function supports tuple-sequences. The method returns the selected tuples of the sequence with an index between the given arguments. The indexes are zero-based and the upper index will be excluded. If the indexes given as strings, it will be transformed to interger values automatically. The function will be used by the select expression to realize the keywords <em>LIMIT</em> and <em>OFFSET</em>. If the interger values are negative or invalid an error will be raised. If the indexes are out of bounds the function will return the tuples with an index in range of the tuple-sequence and the given arguments.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:slice  ( s =&gt; [ "a" , "b" , "c" , "d" ] , low =&gt; 1 , high =&gt; 2 )
2:      =&gt; [ "a" ]
3:
4:      fn:slice  ( s =&gt; [ "a" , "b" , "c" , "d" ] , low =&gt; 3 , high =&gt; 10 )
5:      =&gt; [ "c" , "d" ]
6:
7:      fn:slice  ( s =&gt; [ "a" , "b" , "c" , "d" ] , low =&gt; "a" , high =&gt; "-1" )
8:      =&gt;  raises an error</tt></pre>
</div></div>
<h5 id="_count_2">count</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/count">http://psi.topicmaps.org/tmql/1.0/functions/count</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:count (s : tuple-sequence) return integer</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>count</em> returns the number of tuples of the tuple sequence. The function expected one argument which should be a tuple sequence or an atom. The behaviour of the function is dependent from given arguments. If an atom is given the method will return 1 every time. If it is an tuple sequence it will return the number of contained items.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:count  ( s =&gt; [ "a" , "b" , "c" , "d" ]  )
2:      =&gt; 4
3:
4:      fn:count  ( s =&gt; "b" )
5:      =&gt; 1
6:
7:      fn:count  ( s =&gt; [ ] )
8:      =&gt;  0</tt></pre>
</div></div>
<h5 id="_uniq_2">uniq</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/uniq">http://psi.topicmaps.org/tmql/1.0/functions/uniq</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:uniq (s : tuple-sequence) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>uniq</em> unifies the given tuple sequence. As an interpretation of the current draft each tuple sequence can contain each tuple multiple times. The function removes all multiple references of the same tuple in the given sequence. As arguments the function expects exactly one tuple sequences. The functions is used by the select expression to realize the keyword <em>UNIQUE</em>. The indexes of the tuples in the tuple sequence will be changed.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:uniq  ( s =&gt; [ "a" , "b" , "a" , "b" ]  )
2:      =&gt; [ "a" , "b" ]</tt></pre>
</div></div>
<h5 id="_concat_2">concat</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/concat">http://psi.topicmaps.org/tmql/1.0/functions/concat</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">++</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:concat (s : tuple-sequence, t : tuple-sequence) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">1</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>concat</em> combine two tuple sequence to a new one. The functions adds all tuples of the second sequence to the first sequence. If one of the arguments is an atom instead of a sequence, a new sequence will be created and the atoms will be added. While the combination any ordering is honored.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:concat  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt; "a" )
2:      =&gt; [ "a" , "b" , "a" , "b" , "a" ]
3:
4:      fn:concat  ( s =&gt; "a"  , t =&gt; "b" )
5:      =&gt; [ "a" , "b" ]
6:
7:      fn:concat  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt;  [ "a"  , "c" ] )
8:      =&gt; [ "a" , "b" , "a" , "b" , "a" , "c" ]</tt></pre>
</div></div>
<h5 id="_except_2">except</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/except">http://psi.topicmaps.org/tmql/1.0/functions/except</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">&#8201;&#8212;&#8201;</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:except (s : tuple-sequence, t : tuple-sequence) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">1</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>except</em> produces a tuple sequence where all tuple which appear in t are removed from s. If one of the arguments is an atom instead of a sequence, a new sequence will be created an the atoms will be added. There is no effect for the ordering. If the first tuple sequence contains an element of the second one multiple times, all references of this element will be removed.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:except  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt; "a" )
2:      =&gt; [ "b" , "b" ]
3:
4:      fn:except  ( s =&gt; "a"  , t =&gt; "b" )
5:      =&gt; [ "a" ]
6:
7:      fn:except  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt;  [ "a"  , "c" ] )
8:      =&gt; [ "b" , "b" ]</tt></pre>
</div></div>
<h5 id="_compare_2">compare</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/compare">http://psi.topicmaps.org/tmql/1.0/functions/compare</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>symbolic pattern</strong></p></td>
<td align="left" valign="top"><p class="table">==</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:compare (s : tuple-sequence, t : tuple-sequence) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>precedence</strong></p></td>
<td align="left" valign="top"><p class="table">1</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>compare</em> produces a tuple sequence of all tuples which appear in s and t. Any tuple of the sequence s which is not contained by t will be removed from s. If one of the arguments is an atom instead of a sequence, a new sequence will be created an the atoms will be added. There is no effect for the ordering. The number of references of a tuple element will not be considered.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:compare  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt; "a" )
2:      =&gt; [ "a" , "a" ]
3:
4:      fn:compare  ( s =&gt; "a"  , t =&gt; "b" )
5:      =&gt; [ ]
6:
7:      fn:compare  ( s =&gt; [ "a" , "b" , "a" , "b" ]  , t =&gt;  [ "a"  , "c" ] )
8:      =&gt; [ "a" , "a" ]</tt></pre>
</div></div>
<h5 id="_zigzag_2">zigzag</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/zigzag">http://psi.topicmaps.org/tmql/1.0/functions/zigzag</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:zigzag (s : tuple-sequence) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>zigzag</em> is the reverse function of <em>zagzig</em> and returns a single tuple filled with all values from all tuples. The function can be used to speed up the application because indexes of tuples run faster than indexes within the tuple sequence.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:zigzag  ( s =&gt; [ [ "a" , "b" ] , [ "a" , "b" ] )
2:      =&gt; [ "a" , "b" , "a" , "b" ]
3:
4:      fn:zigzag  ( s =&gt; [ "a" , [ "a" , "b" ] )
5:      =&gt; [ "a" , "a" , "b" ]</tt></pre>
</div></div>
<h5 id="_zagzig_2">zagzig</h5>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/zagzig">http://psi.topicmaps.org/tmql/1.0/functions/zagzig</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:zagzig (s : tuple-sequence) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>zagzig</em> is the reverse function of <em>zigzag</em> and returns a tuple sequence filled by singleton tuples containing an element of the origin tuple. The index of the singleton tuple in context of the sequence will be the same than the index of the item contained by the new singleton tuple in context of the origin tuple.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      fn:zagzig  ( s =&gt;  [ "a" , "b" , "a" , "b" ] )
2:      =&gt; [ [ "a" ] , [ "a" ] , [ "a" ] , [ "a" ] )</tt></pre>
</div></div>
<h4 id="_implementing_your_own_function">3.5.2. Implementing your own function</h4>
<div class="paragraph"><p>The tmql4j engine provides an API to integrate your own functions. The function can be used in the query by the given identifier. This chapter tries to explain how to define a new function at the example of the function <em>length</em> shown in the upper sections.</p></div>
<div class="paragraph"><p>To define your own function we have to create a new function interpreter implementing the API interface <em>IFunctionInvocationInterpreter</em>.  The function interpreter will be called during the interpretation process to handle the function in relation to the current query. Each function interpreter will be initialized one times for each position in the parsing tree, that means if the function is used as a part of the select clause of a select expression, the interpreter will be initialized exactly at the time, the function will be interpret first. This generated instance will be stored by the internal function handler and called if the function is used again. But if the function is used two times at different parts of the query, two instances will be created.</p></div>
<div class="paragraph"><p>At first we have to create a new function interpreter class as shown in the next code snippet.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public class LengthFunctionInvocationInterpreter extends
2:              ExpressionInterpreterImpl&lt;FunctionInvocation&gt; implements
3:                      IFunctionInvocationInterpreter {
4:              ....
5:      }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>A simple notation to create new function interpreter is to named it by the function identifier <em>Length</em> in combination with the postfix <em>FunctionInvocationInterpreter</em>. The class has to implements the API interface <em>IFunctionInvocationInterpreter</em> as shown in line 3. To use the interpreter in the context of a TMQL query it also has to extend the abstract class <em>ExpressionInterpreterImpl</em> with the type argument <em>FunctionInvocation</em>. An expression interpreter is used by the tmql4j handler during the interpretation process to handle the expression of the specific type given by the type argument.</p></div>
</div></div>
<div class="paragraph"><p>The new function interpreter has to implements there inherit methods. The first method only returns the internal identifier of the function use to store it as a topic of the internal environment map. The given identifier shall be unique to avoid side effects.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public String getItemIdentifier() {
2:              return "fn:length";
3:      }</tt></pre>
</div></div>
<div class="paragraph"><p>The second method simply returns the number of expected variables used to handle the function.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public long getRequiredVariableCount() {
2:              return 1;
3:      }</tt></pre>
</div></div>
<div class="paragraph"><p>The last method <em>interpret</em> represent the core functionality of the function interpreter and will be called if the function shall be handled.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public void interpret(TMQLRuntime runtime) throws TMQLRuntimeException {
2:              QueryMatches results = new QueryMatches(runtime);
3:              runtime.getRuntimeContext().pushToStack();
4:
5:              /*
6:              * call sub-expression
7:              */
8:              IExpressionInterpreter&lt;?&gt; interpreter = getInterpreters(runtime).get(0);
9:              interpreter.interpret(runtime);
10:
11:             /*
12:              * extract results and check number of parameters
13:              */
14:             QueryMatches parameters = (QueryMatches) runtime.getRuntimeContext().popFromStack().getValue(VariableNames.QUERYMATCHES);
15:             if (parameters.getOrderedKeys().size() &lt; getRequiredVariableCount()) {
16:                     throw new TMQLRuntimeException(getItemIdentifier() + "() requires " + getRequiredVariableCount() + " parameter.");
17:             }
18:
19:             /*
20:              * iterate over parameters
21:              */
22:             for (Map&lt;String, Object&gt; tuple : parameters) {
23:                     Object sequence = tuple.get("$0");
24:                     Map&lt;String, Object&gt; result = new THashMap&lt;String, Object&gt;();
25:                     /*
26:                      * check if value is a sequence
27:                      */
28:                     if (sequence instanceof Collection&lt;?&gt;) {
29:                             ITupleSequence&lt;Integer&gt; lengths = runtime.getProperties().newSequence();
30:                             /*
31:                              * add length of each string to a new sequence
32:                              */
33:                             for (Object obj : (Collection&lt;?&gt;) sequence) {
34:                                     lengths.add(obj.toString().length());
35:                             }
36:                             result.put(QueryMatches.getNonScopedVariable(), lengths);
37:                     }
38:                     /*
39:                      * add length of the string to result tuple
40:                      */
41:                     else {
42:                             result.put(QueryMatches.getNonScopedVariable(), sequence
43:                                             .toString().length());
44:                     }
45:                     results.add(result);
46:             }
47:             runtime.getRuntimeContext().peekFromStack().createAndAddToOrSetTo( VariableNames.QUERYMATCHES, results);
48:     }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The tuple sequence representing the result of an interpretation task of an expression will be encapsulated by an instance of the class <em>QueryMatches</em>. In line 2 we create a new instance to store the results.</p></div>
<div class="paragraph"><p>The processing model of the tmql4j engine based on the indirect communication between the the different expression at the different tree levels. The communication based on a stack storing all variable bindings which are valid for the current expression instance. If a new expression interpreter gain control of the tmql4j engine it has to push a new variable set on top of the stack before calling any subexpressions as you see in line 3. The production of a function in TMQL describe a subexpression containing all parameters of this function interpretation, so have to call the underlying subexpression first, as we see in line 8 and 9.</p></div>
<div class="paragraph"><p>To get the results of this interpretation the interpreter has to pop the variables set which was added before from the internal stack ( line 14 ). The results are stored by the variable <em>VariableNames.QUERYMATCHES</em>, because of that we has to call the <em>getValue</em> method with the variable name.</p></div>
<div class="paragraph"><p>In line 15 until 17 we will check the number of contained arguments and raise an exception if the number differes from the expected one given by the method <em>getRequiredVariableCount</em>.</p></div>
<div class="paragraph"><p>Between line 22 and 46 the code realized the function interpretation. In line 23 we extracted the argument representing the tuple sequence by using the index variable <em>$0</em>.</p></div>
<div class="paragraph"><p>The last step is to store the overall results at the stack to return it to the parent expression handler. The results are also identified by the variable <em>VariableNames.QUERYMATCHES</em> as we see in line 47.</p></div>
</div></div>
<div class="paragraph"><p>After finishing our implementation we have to register our new function at the tmql4j runtime using the provided interface.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      runtime.getLanguageContext().getFunctionRegistry().registerFunction("fn:length", LengthFunctionInvocationInterpreter.class);</tt></pre>
</div></div>
<div class="paragraph"><p>Now we can use our new function.</p></div>
<h3 id="_engine_modules">3.6. Engine-Modules</h3><div style="clear:left"></div>
<div class="paragraph"><p>TMQL4J is designed as a process chain of simple modules. Each module provides a simple or atomic function in context of the querying process and will be handled by a processing task of the runtime. The modules can be exchanged to adapt the implementation to your own business cases. The processing chain is encapsulated by the tmql4j runtime container and can not be access directly.</p></div>
<h4 id="_pre_processing_module">3.6.1. Pre-Processing Module</h4>
<div class="paragraph"><p>Before execution the query instance is called by the TMQL processor to handle any pre-processing stuff.</p></div>
<h5 id="_screener">screener</h5>
<div class="paragraph"><p>A screener is a special part of a compiler and clean the given string representation of the TMQL query by removing comments and whitespaces or new-line-commands. The screener implementation of the tmql4j engine is represented by the API interface <em>IScreener</em>. The base implementation of this module is the <em>TMQLScreener</em> which removes all comments contained by the given query symbolized by the hex character <em>#</em>. Line breaks will be removed by replacing it with a single space. The result of the screening process will be a single line string representation of the origin query.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      SELECT $p # set the variable
2:              WHERE $p ISA person # boolean condition
3:
4:      =&gt; SELECT $p WHERE $p ISA person</tt></pre>
</div></div>
<h5 id="_whitepacer">whitepacer</h5>
<div class="paragraph"><p>The whitespacer is a special part of the pre-processing module and cleaning the whitespaces of the given query. The whitespacer add optional whitespaces of the current draft missing by the user. If there are multiple whitespaces at a position where at least one is required by the draft. Protected whitespaces will not be changed. A whitespace is protected if it is a part of a string literal or an XML content. The whitespacer is represented by the API interface <em>IWhitespacer</em> and the base implementation is <em>TMQLWhiteSpacer</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      SELECT $p&gt;&gt;characteristics tm:name
2:              WHERE $p ISA person
3:
4:      =&gt; SELECT $p &gt;&gt; characteristics tm:name WHERE $p ISA person</tt></pre>
</div></div>
<h4 id="_lexical_scanner">3.6.2. Lexical scanner</h4>
<div class="paragraph"><p>The lexical scanner is a special program module of the engine to split the given query into language-specific elements, called tokens. Each token represents a logically independent and language specific part of the query, like keywords or variables names. All tokens are defined by the lowest grammar level - token level. The lexer is represented by the API interface <em>ILexer</em> and the base implementation is <em>TMQLLexer</em>.</p></div>
<div class="paragraph"><p>At first the lexical scanner split the given string-represented query using a special tokenizer class provided by the internal engine processor. The tokenized string will be checked for knwon keywords element by element and will be represented by a language-specific token. The result of lexical scanning will be a chain of string-represented tokens and language-specific tokens.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      SELECT $p / tm:name
2:              WHERE $p ISA person
3:
4:      =&gt; [ SELECT , $p , &gt;&gt; , characteristics , tm:name , &gt;&gt; , atomify , WHERE , $p , ISA , person ]</tt></pre>
</div></div>
<h4 id="_parser_module">3.6.3. Parser Module</h4>
<div class="paragraph"><p>The parser is the core module of the tmql4j engine. It converts the lexical tokens to a tree-structure representing the semantic structure of the given query. Each node of the parser tree represents a production rule of the TMQL draft and contains a number of children, if the production rule contains terminals representing new production rules. Leafs can only be simple atoms or a simple step. The tree structure will be an instance of the API interface <em>IParserTree</em> and will be created by an implementation of <em>IParser</em>. The base implementation of the parser is the class <em>TMQLParser</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      SELECT $p / tm:name
2:              WHERE $p ISA person
3:
4:      =&gt; QueryExpression([SELECT, $p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify, WHERE, $p, ISA, person])
5:              |--SelectExpression([SELECT, $p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify, WHERE, $p, ISA, person])
6:              |--SelectClause([SELECT, $p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify])
7:              |       |--ValueExpression([$p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify])
8:              |               |--Content([$p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify])
9:              |                       |--QueryExpression([$p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify])
10:             |                               |--PathExpression([$p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify])
11:             |                                       |--PostfixedExpression([$p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify])
12:             |                                               |--SimpleContent([$p, &gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify])
13:             |                                                       |--Navigation([&gt;&gt;, characteristics, tm:name, &gt;&gt;, atomify])
14:             |                                                               |--Step([&gt;&gt;, characteristics, tm:name])
15:             |                                                               |--Step([&gt;&gt;, atomify])
16:             |--WhereClause([WHERE, $p, ISA, person])
17:                     |--BooleanExpression([$p, ISA, person])
18:                             |--BooleanPrimitive([$p, ISA, person])
19:                                     |--ExistsClause([$p, ISA, person])
20:                                             |--Content([$p, ISA, person])
21:                                                     |--QueryExpression([$p, ISA, person])
22:                                                             |--PathExpression([$p, ISA, person])
23:                                                                     |--ISAExpression([$p, ISA, person])
24:                                                                             |--SimpleContent([$p])
25:                                                                             |--SimpleContent([person])</tt></pre>
</div></div>
<h4 id="_interpreter_module">3.6.4. Interpreter Module</h4>
<div class="paragraph"><p>The interpreter module is represented by a set of many expression interpreters. An interpreter is responsible for one specific expression type and will be instantiate if a expression of this type is part of the parsing tree. The overall results of the interpretation task will be an instance of <em>QueryMatches</em> which will be transformed to a <em>IResultSet</em> by the underlying results processor. An expression interpreter will be an instance of the API interface <em>IExpressionInterpter</em> or the abstract class <em>ExpressionInterpreterImpl</em>.</p></div>
<h4 id="_result_processing_module">3.6.5. Result-Processing Module</h4>
<div class="paragraph"><p>The last module of the default processing chain will be the result processor. The result processor transform and auto-reduce the interpretation results. The results will be transformed to an instance of <em>IResultSet</em> and will be reduced to a two-dimensional result.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      {
2:              [ "a" , [ "c" , "b" ] ] ,
3:              [ "x" , [ "y0" , "y1" ] , [ "z0" , "z1" ] ]
4:      }
5:
6:      =&gt;      {       [ "a" , "c" ] ,
7:                      [ "a" , "b" ] ,
8:                      [ "x" , "y0" , "z0" ] ,
9:                      [ "x" , "y1" , "z0" ] ,
10:                     [ "x" , "y0" , "z1" ] ,
11:                     [ "x" , "y1" , "z1" ] }</tt></pre>
</div></div>
<h4 id="_module_integration">3.6.6. Module integration</h4>
<div class="paragraph"><p>The tmql4j engine provides two methods to migrate or adapt the modules of the tmql4j runtime container. The migration or adaptation of some modules can be necessary in relation to gain business goals using the tmql4j engine.</p></div>
<h5 id="_adapt_an_existing_module">Adapt an existing module</h5>
<div class="paragraph"><p>If a developer only needs to adapt one of the internal modules of the default processing chain like the lexical scanner  or anything else, the property handler can used to integrate own implementations of the core interfaces representing each of this modules.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public class MyLexer implements ILexer{
2:              ....
3:      }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>At first has to implement our own module class extends an existing implementation of a module interface or implements the interface itselfs. In this example we create our own lexical scanner with the name <em>MyLexer</em> as we see in line 1.</p></div>
</div></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      runtime.getProperties().setProperty(TMQLRuntimeProperties.LEXER_IMPLEMENTATION_CLASS, MyLexer.class.getName());</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The last step is to tell the tmql4j engine container to use our implementation of the lexical scanner interface. In line 1 we call the properties of the current runtime instance and changing the property <em>lexer-implementation-class</em> representing the lexical scanner implementation used during the querying process.</p></div>
</div></div>
<h5 id="_migrate_a_new_module">Migrate a new module</h5>
<div class="paragraph"><p>It is also possible to create and add a new module to the tmql4j engine. In this case the developer has to implementing its own <em>ITMQLRuntime</em> implementation and its own <em>IProcessingChain</em> to add the module at the correct position during the querying process.</p></div>
<h3 id="_results">3.7. Results</h3><div style="clear:left"></div>
<div class="paragraph"><p>The results of a querying process are represented similar to the Java Database Connectivity ( JDBC ) <em>ResultSet</em>. The result processor transform the sequence of tuples generated by the interpretation module to an instance of <em>IResultSet</em>. The type of the result set will be different dependent from the property value and the expression type. The user can add its own implementation of a <em>IResultSet</em> to add specific functions or represent the data in the desired way.</p></div>
<div class="paragraph"><p>The tmql4j engine will automatically change the implementation of the result set which is compatible to the result types. If the query returns XML content the engine will change the result set class to an implementation of <em>XMLResult</em>. If the interpreter returns CTM content, the result set will be an instance of <em>CTMResult</em>.</p></div>
<div class="paragraph"><p>The <em>IResultSet</em> interface define a method to check the type of the result set based on an internal enumeration.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      IResultSet set = query.getResults();
2:      return set.getResultType();
3:
4:      =&gt; "TMAPI" or "XML" or "CTM"</tt></pre>
</div></div>
<h4 id="_using_an_iresultset">3.7.1. Using an IResultSet</h4>
<div class="paragraph"><p>The <em>IResultSet</em> is designed similar to the JDBC <em>ResultSet</em> and can be used in a similar way. The result set provides a functionality to iterate over the contained results represented by the interface <em>IResult</em>. An instance of <em>IResult</em> represents exactly one tuple of the interpretation result and contains a set of literals and items representing the tuple items. The <em>IResult</em> class can also be used by iteration like the <em>IResultSet</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      IResultSet&lt;?&gt; set = query.getResults();
2:              for ( IResult result : set ){
3:                      for ( Object item : result ){
4:                              ...
5:                      }
6:      }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>In line 1 we extract the result set from the query instance <em>query</em> using the method <em>getResults</em>. The wildcard <em>?</em> is used because we don&#8217;t know the <em>IResult</em> class contained by the result set. Because of the fact that <em>IResult</em> and <em>IResultSet</em> are extending the Java <em>Iterable</em> interface, we simply can iterate over the contained elements using the for-loop as we see in line 2 and 3.</p></div>
</div></div>
<h5 id="_tmapi_results">TMAPI-Results</h5>
<div class="paragraph"><p>The base result type is a TMAPI result set containing plain java objects and TMAPI objects representing the querying results. This result type will be generated by the result processor during the querying process of each expression type except flwr-expression return XML or CTM contents.</p></div>
<h5 id="_ctm_results">CTM-Results</h5>
<div class="paragraph"><p>Using the flwr-expression of the current language draft a querying can returns a set of CTM content. This special result type will be handle by an instance of <em>CTMResult</em> and <em>CTMFragment</em>. The special implementation of <em>IResult</em> contains additional methods which can be important to handle the internal CTM content in an easy way.</p></div>
<div class="paragraph"><p>The method <em>resultsAsTopicMap()</em> returns a topic map construct representing all CTM fragments as one topic map instance. Each fragment will be parsed by a CTM reader and will be merged in the topic map instance. The overall result will be returned by this method.</p></div>
<div class="paragraph"><p>The method <em>resultsAsMergedCTM()</em> returns a topic map serialization containing all CTM fragments of the result set. Each fragment will be parsed by a CTM reader and will be merged in the topic map instance which will be serialized by a CTM writer.</p></div>
<h5 id="_xml_results">XML-Results</h5>
<div class="paragraph"><p>Using the flwr-expression of the current language draft a querying can returns a set of XML content. This special result type will be handle by an instance of <em>XMLResult</em> and <em>XMLFragment</em>. The special implementation of <em>IResult</em> contains additional methods which can be important to handle the internal XML content in an easy way.</p></div>
<div class="paragraph"><p>The method <em>toXMLDocument()</em> returns an <em>org.w3c.dom.Document</em> representing the whole XML result. The document will be created by adding all XML fragments to one content. If the result contains more than one fragment a additional root node <em>xml-root</em> will be added.</p></div>
<div class="paragraph"><p>The method <em>resultsAsMergedXML()</em> return a string representing the whole XML result. The document content will be returned as a string.</p></div>
<h4 id="_creating_your_own_result_set">3.7.2. Creating your own Result Set</h4>
<div class="paragraph"><p>The tmql4j engine provides the functionality to insert own implementations of a result set. The implementation only has to inherit from the <em>IResultSet</em> interface and has to be registered using the property handler of the runtime container and the property <em>result-set-implementation-class</em>.</p></div>
<h3 id="_tmql_api">3.8. TMQL API</h3><div style="clear:left"></div>
<div class="paragraph"><p>Simply the topic maps query engine tmql4j isn&#8217;t a query engine only supports topic maps engine based on the TMAPI specification. In addition the engine provides a set of interfaces to add any backend implementation providing informations represented as topic map constructs.</p></div>
<h4 id="_the_itmqlruntime_interface">3.8.1. The ITMQLRuntime Interface</h4>
<div class="paragraph"><p>The interface definition called <em>ITMQLRuntime</em> specifies a runtime implementation handle any topic map query language.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>public interface ITMQLRuntime {

        public void run(IQuery query) throws TMQLRuntimeException;

        public IQuery run(TopicMap topicMap, String query) throws TMQLRuntimeException;

        public ILanguageContext getLanguageContext();

        public IExtensionPointAdapter getExtensionPointAdapter() throws UnsupportedOperationException;

        public boolean isExtensionMechanismSupported();

        public void setTopicMapSystem(TopicMapSystem system);

        public TopicMapSystem getTopicMapSystem();

        public IParserTree parse(final String query) throws TMQLRuntimeException;

        public IParserTree parse(final IQuery query) throws TMQLRuntimeException;

        public ITmqlProcessor getTmqlProcessor();

        public IConstructResolver getConstructResolver();

         public String getLanguageName();
}</tt></pre>
</div></div>
<div class="paragraph"><p>The method <em>getConstructResolver</em> is used to identify a topic by the given identifier represented by the second argument. The first argument is a reference of the current querying context. In relation to the TMAPI the method has to return an instance of <em>Construct</em> representing any construct of a topic map, like topics, associations or roles. The method has to return the data set for the given identifier, but may not return <em>null</em> any time. If the construct cannot found or is unknown for the called backend <em>null</em> should be returned.</p></div>
<div class="paragraph"><p>The method <em>getTmqlProcessor</em> is called during the querying process to fetch a processor instance executes the querying process. The processor encapsulate the lexical scanner, the parser and result processing modules.</p></div>
<div class="paragraph"><p>The method <em>getExtensionPointAdapter</em> returns the internal reference of the extension point adapter if the runtime supports extension mechanism, which can be check by calling the method <em>isExtensionMechanismSupported</em>. If the method is called if the mechanism is not supported, an exception is caused.</p></div>
<div class="paragraph"><p>The methods <em>run</em> and <em>parse</em> are called by the upper application.</p></div>
<h4 id="_the_iconstructresolver_interface">3.8.2. The IConstructResolver Interface</h4>
<div class="paragraph"><p>The interface definition represents a utility module to find a construct by different identifier types, like its subject-identifiers, subject-locators or item-identifiers.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public interface IConstructResolver {
2:
3:              public Topic getTopicBySubjectIdentifier(final IContext context, final String identifier);
5:
6:              public Topic getTopicBySubjectLocator(final IContext context,final String identifier);
8:
9:              public Construct getConstructByItemIdentifier(final IContext context,final String identifier);
11:
12:             public Construct getConstructByIdentifier(final IContext context,final String identifier);
14:
15:     }</tt></pre>
</div></div>
<div class="paragraph"><p>The first parameter of each method contains the current context of querying processes, like the topic map instance it-self, the query and some additional prefixes defined by the query.</p></div>
<div class="paragraph"><p>Like the name of <em>getTopicBySubjectIdentifier</em> method indicates, implements the method the functionality to get a topic item by its subject-identifier. As parameters the method will get an unique subject-identifier of a topic as string-represented IRI and an instance of the topic map construct, contains the information. The topic map construct can also be an abtraction container for the underlying backend. As alternative the function <em>getTopicBySubjectLocator</em> returns a topic item represented by its subject-locator. Both method has to return the topic item identified by the given IRI but never null. If the construct cannot be resolved, <em>null</em> shall be returned.</p></div>
<div class="paragraph"><p>In relation to the topic maps data model the third method <em>getConstructByItemIdentifier</em> has to return an topic map construct identified by it item-identifier given by the first argument. If there is no construct with this item-identifier, <em>null</em> shall be returned.</p></div>
<div class="paragraph"><p>The last method combines the three functions to get a topic map construct by its identifiers. Please note that this method can be ambiguous, if the topic map contains a construct with the IRI as subject-locator and one with the IRI as subject-identifier. If the topic map scheme of the queried topic map or the abstract layer contains a restriction to forbid something like that, the method can use securely.</p></div>
<h4 id="_the_inavigationaxis_interface">3.8.3. The INavigationAxis Interface</h4>
<div class="paragraph"><p>The current draft of the topic maps query language contains a special navigation expression type based on the proxies defined by the topic maps reference model. The draft describe 12 axis as abstraction of the topic maps graph defined by the relation between any topic map constructs like associations and roles. In relation to this axis the tmql4j API contains the interface <em>INavigationAxis</em> representing one of this axis.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public interface INavigationAxis {
2:
3:              TopicMap getTopicMap() throws NavigationException;
4:
5:              void setTopicMap(TopicMap topicMap);
10:
11:             NavigationAxis getNavigationType();
12:
13:             boolean supportsForwardNavigation(final Object construct, final Object optional) throws NavigationException;
14:
15:             boolean supportsForwardNavigation(final Object construct, final Object optional) throws NavigationException;
16:
17:             ITupleSequence&lt;?&gt; navigateForward(final Object construct) throws NavigationException;
18:
19:             ITupleSequence&lt;?&gt; navigateForward(final Object construct, final Object optional) throws NavigationException;
20:
21:             Class&lt;?&gt; getForwardNavigationResultClass(final Object construct) throws NavigationException;
22:
23:     }</tt></pre>
</div></div>
<div class="paragraph"><p>The method <em>setTopicMap</em> used by the runtime container to set the current topic map to the navigation axis implementation. The given topic maps can be used by the implementation to realize the navigation step if it is necessary.</p></div>
<div class="paragraph"><p>The <em>getNavigationType</em> returns an enumeration value describing the type of this axis. The core engine defines enumeration values for each of the predefined navigation axis. To add new axis the extension has to extend this enumeration and add new values.</p></div>
<div class="paragraph"><p>Some of the TMQL axis supporting an optional type parameter in addition to the navigation start represented by a topic reference. Because of that most of the methods of the interface are overloaded to realize the usage with an optional argument or without it. The method <em>supportsForwardNavigation</em> checks if the given start node of the abstract topic maps graph will be supported by the axis and if the optional type can be used if it is not <em>null</em>.</p></div>
<div class="paragraph"><p>The navigation step over the axis will be provided by the <em>navigateForward</em> method an will return a tuple sequence containing all topic map constructs as target nodes of the navigation step.</p></div>
<div class="paragraph"><p>The last method <em>getForwardNavigationResultClass</em>  returns the class object representing the expected result type of a navigation step of this navigation axis.</p></div>
<div class="paragraph"><p>In addition to the method containing the word forward there are a correspondent to realize the method in backward direction as it is described by the current draft.</p></div>
<div class="paragraph"><p>If any of the navigation functions fails, the method will throw an exception of type <em>NavigationException</em>.</p></div>
<h3 id="_tmql4j_extensions">3.9. TMQL4J Extensions</h3><div style="clear:left"></div>
<div class="paragraph"><p>The tmql4j engine provides a framework to include your own extensions quite simple. Using Java Service Providers the extension will be registered automatically if the implementation class is in the class path.</p></div>
<div class="paragraph"><p>The engine currently supports two different extension types - language extensions and engine extensions.</p></div>
<h4 id="_engine_extensions">3.9.1. Engine Extensions</h4>
<div class="paragraph"><p>An engine extension simple add or change some functionality of the querying process or the engine workflow. To learn how to integrate your own extensions, the following example showing an extension implementing a multi-threaded expression interpreter for quantified-expressions of TMQL.</p></div>
<div class="paragraph"><p>To intergrate an engine extension the plugin has to contain an implementation of the <em>IExtensionPoint</em> interface representing the entry point of the plugin itselfs. An extension point is used by the runtime to initialize and register the plugin. Using Java services the extension adapter will find all implementations of the <em>IExtensionPoint</em> interface.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public interface IExtensionPoint {
2:
3:              /**
4:              * Method called by the runtime to register the extension endpoint before
5:              * running the query process.
6:              *
7:              * @param runtime
8:              *            the calling runtime
9:              * @throws TMQLExtensionRegistryException
10:             *             thrown if an exception caused by the internal runtime
11:             */
12:             public void registerExtension(ITMQLRuntime runtime)
13:                     throws TMQLExtensionRegistryException;
14:
15:             /**
16:             * Each extension point has to define an unique extension point id used to
17:             * represent the extension point in context of the current TMQL runtime. If
18:             * two extension points has the same identifier the extension adpater will
19:             * throw an exception during the initialization time of extension points on
20:             * startup.
21:             *
22:             * @return the unique id
23:             */
24:             public String getExtensionPointId();
25:
26:     }</tt></pre>
</div></div>
<div class="paragraph"><p>An extension point has to implement only two methods of the interface to realize the usage as a part of the tmql4j engine. The method <em>getExtensionPointId</em> has to return a string-represented and unique identification of the plugin. The unique ID will be used by the runtime to identify the plugin during the runtime process. If the plugins are integrate using the same identification string, an exception will be raised.</p></div>
<div class="paragraph"><p>The main method of the extension point handled by the method <em>registerExtension</em>. The method will be called by the extension adapter and get a reference of the current runtime container, which tries to load the plugin. Using this method the developer can creates changes or integrate new interpreters for existing expression types. To register your own interpreter class, the interpreter registry has to be used which is managed by the runtime properties of the current runtime container.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public class MultiThreadExtensionPoint implements IExtensionPoint {
2:
3:              /**
4:               * {@inheritDoc}
5:               */
6:              @Override
7:              public void registerExtension(ITMQLRuntime runtime)
8:                      throws TMQLExtensionRegistryException {
9:                              try {
10:                                             runtime.getLanguageContext().getInterpreterRegistry().registerInterpreterClass( ExistsClause.class,
                                                                MultiThreadExistsClauseInterpreter.class);
11:                             } catch (TMQLException e) {
12:                                     throw new TMQLExtensionRegistryException(e);
13:                             }
14:             }
15:
16:             /**
17:              * {@inheritDoc}
18:              */
19:             @Override
20:             public String getExtensionPointId() {
21:                     return "tmql4j.extension.mutlithreaded";
22:             }
23:
24:     }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>This extension point implementations is used as entry point of the multithread extension for quantified-expression. In line 21 the class return the string literal <em>tmql4j.extension.mutlithreaded</em> as identification for the current plugin. In code line 10 the interpreter class <em>MultiThreadExistsClauseInterpreter</em> is registered as the interpreter for all expressions of the type <em>ExistsClause</em>. After this registration the tmql4j engine will create an instance of the interpreter class for each exists clause in the context of the parsing tree.</p></div>
<div class="paragraph"><p>To register the interpreter class the runtime reference is used to get the runtime properties calling the method <em>getProperties</em>. The property handler provides the method <em>getRegistry</em> to get the internal interpreter registry instance which should be used to add new interpreters. To realize that the method <em>registerInterpreterClass</em> with two arguments is used. The first argument represents the expression type as Java class and the second argument is a Java class representing the interpreter.</p></div>
</div></div>
<div class="paragraph"><p>Please note that plugins can interfere with each other. Sometimes a plugin functionalty is overlapped by another plugin. It can not be predict which plugin will be used or which function, because the order of including is haphazardly. Plugins allways covers functionality of the core engine which cannot be used if the plugin is intergrated. Take care!</p></div>
<div class="paragraph"><p>To use Java service provider technology, the jar file must be include a file named <em>de.topicmapslab.tmql4j.extensions.model.IExtensionPoint</em> only includes one text line with the full qualified name of the extension point implementation.  The file has to be located in the folder <em>META-INF\services</em>.</p></div>
<h4 id="_language_extensions">3.9.2. Language Extensions</h4>
<div class="paragraph"><p>As second plugin type, the tmql4j engine supports language extensions. A language extension should be used to add some additional productions to the core language defined in the current draft. The extension may not overwrite some functionality of the current engine, it only has to add some new expression types and all which seems to be necessary to realize the interpretation and the usage of the language extension.</p></div>
<div class="paragraph"><p>To migrate a language extension the plugin has to implement the abstract interface <em>ILanguageExtension</em>. A language extension is a extension point and has to implement the same methods. An extension point is used by the runtime to initialize and register the plugin. Using Java services the extension adapter will find all implementations of the <em>IExtensionPoint</em> interface.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public interface ILanguageExtension extends IExtensionPoint {
2:
3:              /**
4:               * Checks if the language extension extends the given expression type. If
5:               * the language extension add new productions starting with the given
6:               * expression type it has to return &lt;code&gt;true&lt;/code&gt;, &lt;code&gt;false&lt;/code&gt;
7:               * otherwise.
8:               *
9:               * @param expressionType
10:              *            the extended expression type
11:              * @return &lt;code&gt;true&lt;/code&gt; if the extension based on the expression type.
12:              */
13:             public boolean extendsExpressionType(
14:                     final Class&lt;? extends IExpression&gt; expressionType);
15:
16:             /**
17:              * Return the language extension entry defining the entry point for using
18:              * the extension during the querying process.
19:              *
20:              * @return the extension entry
21:              */
22:             public ILanguageExtensionEntry getLanguageExtensionEntry();
23:
24:     }</tt></pre>
</div></div>
<div class="paragraph"><p>A langugae extension has to implement the two method defined in line 13 and 22. The method <em>extendsExpressionType</em> seems to be used by the runtime to check if the extension is based on the current expression type. If the langauge extension add some functionality based on a query-expression, like a new sub-expression for creating new content, it has to return true if the parameter <em>expressionType</em> bind to the <em>QueryExpression</em> class.</p></div>
<div class="paragraph"><p>The method <em>getLanguageExtensionEntry</em> returns a reference of the language extension entry. A language extension entry is used to migrate the new productions.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public interface ILanguageExtensionEntry {
2:
3:              /**
4:               * Returns the expression type used as anchor in the parsing tree.
5:               *
6:               * @return the expression type as anchor in the parsing tree
7:               */
8:              public Class&lt;? extends IExpression&gt; getExpressionType();
9:
10:             /**
11:              * Checks if the given language-specific tokens matching the new production
12:              * of the language extension. The method has to check if the extension an be
13:              * used for the given sub-query.
14:              *
15:              * @param runtime
16:              *            the current runtime container
17:              * @param tmqlTokens
18:              *            the language-specific tokens
19:              * @param tokens
20:              *            the string-represented tokens
21:              * @return &lt;code&gt;true&lt;/code&gt; if the productions can be used,
22:              *         &lt;code&gt;false&lt;/code&gt; otherwise.
23:              */
24:             public boolean isValidProduction(final ITMQLRuntime runtime,
25:                     final List&lt;Class&lt;? extends IToken&gt;&gt; tmqlTokens,
26:                     final List&lt;String&gt; tokens);
27:
28:             /**
29:              * Called by the parser to add new sub-tree nodes using the extension
30:              * anchor.
31:              *
32:              * @param runtime
33:              *            the runtime container
34:              * @param tmqlTokens
35:              *            the language-specific tokens
36:              * @param tokens
37:              *            the string-represented tokens
38:              * @param caller
39:              *            the calling expression
40:              * @param autoAdd
41:              *            flag representing if the sub-tree should add automatically
42:              * @return the created expression
43:              * @throws TMQLInvalidSyntaxException
44:              *             thrown if the expression is invalid
45:              * @throws TMQLGeneratorException
46:              *             thrown if the expression can not be created
47:              */
48:             public IExpression parse(final ITMQLRuntime runtime,
49:                     final List&lt;Class&lt;? extends IToken&gt;&gt; tmqlTokens,
50:                     final List&lt;String&gt; tokens, IExpression caller, boolean autoAdd)
51:                     throws TMQLInvalidSyntaxException, TMQLGeneratorException;
52:     }</tt></pre>
</div></div>
<div class="paragraph"><p>The language extension entry representing the handler of the language extension. The entry will be called during the parsing process for the specified type returned by the method <em>getExpressionType</em> to migrate the new extension ad the current tree node of the parsing tree. The migration takes place in two steps. At first the runtime calls the method <em>isValidProduction</em> with the current list of language-specific tokens. The method is used to check if the current tokens matches to the represented production rule. If the method is true, the method returns <em>true</em>, the method <em>parse</em> will called. The method should create the new sub-tree starting with the current node. The expression has to be added to the parsing tree automatically if the flag <em>autoAdd</em> is true.</p></div>
<div class="paragraph"><p>Please note that the interpreter class and new tokens has to register first during the registration of the extension point. The following example register new tokens and new interpreter classes for a new expression representing an insert statement.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      /**
2:       * {@inheritDoc}
3:       */
4:      @Override
5:      public void registerExtension(ITMQLRuntime runtime)
6:                      throws TMQLExtensionRegistryException {
7:              /*
8:               * register tokens
9:               */
10:             TokenRegistry registry = runtime.getLanguageContext().getTokenRegistry();
11:             registry.register(Insert.class);
12:
13:             /*
14:              * register expression interpreter
15:              */
16:             InterpreterRegistry interpreterRegistry = runtime.getLanguageContext()
17:                             .getInterpreterRegistry();
18:             try {
19:                     interpreterRegistry.registerInterpreterClass(InsertClause.class,
20:                                     InsertClauseInterpreter.class);
21:                     interpreterRegistry.registerInterpreterClass(
22:                                     InsertExpression.class, InsertExpressionInterpreter.class);
23:                     interpreterRegistry
24:                                     .registerInterpreterClass(
25:                                                     de.topicmapslab.tmql4j.extension.tmml.grammar.expressions.QueryExpression.class,
26:                                                     QueryExpressionInterpreter.class);
27:             } catch (TMQLException e) {
28:                     throw new TMQLExtensionRegistryException(e);
29:             }
30:
31:             entry = new ModificationPartLanguageExtensionEntry();
32:     }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The snippet is an abstract of the extension point implementation of the modification part extension of TMQL. The code snippet register a new insert-expression type to the current runtime. First a new language-specific token added in line 11 using the token registry. a new token will be represented by a class extending the interface <em>IToken</em>. In line 19 and 21 two new interpreter class added to the current interpreter registry. The interpreter classes will be used to interpret the expression during the querying process. As you can see the extension register an extended implementation of a query-expression in line 23. After the registration of this language extension, there are two different query-expressions - the origin one and the modification extension. In this case, the core implementation wont be effected by the extension.</p></div>
</div></div>
<div class="paragraph"><p>At last we take a look at the <em>IToken</em> interface.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      public interface IToken {
2:
3:              /**
4:               * Method checks if the token can be represented by the given string literal
5:               *
6:               * @param literal
7:               *            the string literal
8:               * @param runtime
9:               *            the contained runtime
10:              * @return &lt;code&gt;true&lt;/code&gt; if the literal can be represented by this
11:              *         expression type
12:              */
13:             public boolean isToken(final ITMQLRuntime runtime, final String literal);
14:
15:             /**
16:              * Method returns the string representation of the current language token
17:              *
18:              * @return the literal
19:              */
20:             public String getLiteral();
21:
22:     }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The interface represents a specific token of the language of TMQL or some extensions. The method <em>isToken</em> checks if the given literal can be represented as a token of this type. The method <em>getLiteral</em> will return a string-representation of the token type.</p></div>
</div></div>
<div class="paragraph"><p>To use Java service provider technology, the jar file must be include a file named <em>de.topicmapslab.tmql4j.extensions.model.IExtensionPoint</em> only includes one text line with the full qualified name of the extension point implementation.  The file has to be located in the folder <em>META-INF\services</em>.</p></div>
<h3 id="_tmql4majortom_plugin">3.10. Tmql4MaJorToM PlugIn</h3><div style="clear:left"></div>
<div class="paragraph"><p>The MaJorToM plugin of the tmql4j query engine provides a set of new functions only enable in the context of the MaJorToM Topic Maps Engine. The new functions supports spatial and temporal calculations and extraction of information.</p></div>
<h4 id="_best_label_function">3.10.1. Best-Label Function</h4>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/best-label">http://psi.topicmaps.org/tmql/1.0/functions/best-label</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:best-label (i : topic-item) return string</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:best-label (i : topic-item, theme: topic-item) return string</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:best-label (i : topic-item, theme: topic-item, strict: boolean) return string</p></td>
</tr>
</tbody>
</table>
</div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The first argument is the topic item, in which context the best label should be extracted. The second is optional and represents a theme of the scopes, a name should have. The third argument is also optional and represents the strict mode of the best-label function. If the value is <em>true</em> and there is no scope with the given theme for any name item of the topic, the function will return nothing.</p></div>
</div></div>
<div class="paragraph"><p>The <em>best-label</em> function exists in three different versions differ in the number of arguments. The result of the function is a string literal or nothing which will be calculated by the following rules.</p></div>
<div class="olist arabic"><ol class="arabic">
<li>
<p>
If the topic has no names, continue with 6 except the third argument is given and set to the value <em>true</em>. In this case nothing will be returned.
</p>
</li>
<li>
<p>
The names with the TMDM default-name type will be preferred.
</p>
</li>
<li>
<p>
The names with the lowest number of themes in scope will be preferred. As default the unconstrained scope has the highest priority. If the second argument is given, the scopes containing this theme have the highest priority. If there is no scope with the theme and the third argument is given and set to value <em>true</em> nothing will be returned.
</p>
</li>
<li>
<p>
The names with the lowest number of characters will be preferred. The empty string will be ignored.
</p>
</li>
<li>
<p>
The names with the lexicographically lowest value will be preferred.
</p>
</li>
<li>
<p>
The lexicographically lowest subject-identifier will be returned.
</p>
</li>
<li>
<p>
The lexicographically lowest subject-locator will be returned.
</p>
</li>
<li>
<p>
The lexicographically lowest item-identifier will be returned.
</p>
</li>
<li>
<p>
The id will be returned.
</p>
</li>
</ol></div>
<h4 id="_coordinates_in_distance_function">3.10.2. Coordinates-In-Distance Function</h4>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/coordinates-in-distance">http://psi.topicmaps.org/tmql/1.0/functions/coordinates-in-distance</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:coordinates-in-distance (s : string , dist : decimal ) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:coordinates-in-distance (lat : decimal, long : decimal , dist : decimal ) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>coordinates-in-distance</em> exists in two versions differ in the number of arguments. The result of the function will be a sequence of occurrences representing a WGS84 coordinate located nearby the given position. The WGS84 coordinate can be given as string literal matching the following pattern</p></div>
<div class="paragraph"><p>&lt;latitude&gt;';'&lt;longitude&gt;(<em>;</em>&lt;altitude&gt;)?</p></div>
<div class="paragraph"><p>The coordinate can also be given by a latitude and longitude value. The last decimal argument represents the distance in meter between the occurrence value and the given coordinate as maximal value.</p></div>
<h4 id="_distance_function">3.10.3. Distance Function</h4>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/distance">http://psi.topicmaps.org/tmql/1.0/functions/distance</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:distance (s : string , s:string ) return decimal</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:distance (lat1 : decimal, long1 : decimal  , lat2 : decimal, long2 : decimal  ) return decimal</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>distance</em> returns the distance between two WGS84 coordinates given by string literals or latitude and longitude values. The distance will be returned as decimal value measured in meters.</p></div>
<h4 id="_dates_function">3.10.4. Dates Function</h4>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/dates">http://psi.topicmaps.org/tmql/1.0/functions/dates</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates ( ) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>dates</em> returns all occurrences representing a date-time value checked by the datatype <em>xsd:dateTime</em>.</p></div>
<h4 id="_dates_after_function">3.10.5. Dates-After Function</h4>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/dates-after">http://psi.topicmaps.org/tmql/1.0/functions/dates-after</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-after ( s : string ) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-after ( y : integer , m : integer , d : integer  ) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-after ( y : integer , m : integer , d : integer , h : integer , min : integer , s : integer ) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>dates-after</em> returns all occurrences representing a date-time value checked by the datatype <em>xsd:dateTime</em> after a specific date. The date can be defined by a single string literal or as a set of integer values representing the year, month, day and optional the hour, the minute and the second.</p></div>
<h4 id="_dates_before_function">3.10.6. Dates-Before Function</h4>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/dates-before">http://psi.topicmaps.org/tmql/1.0/functions/dates-before</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-before ( s : string ) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-before ( y : integer , m : integer , d : integer  ) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-before ( y : integer , m : integer , d : integer , h : integer , min : integer , s : integer ) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>dates-before</em> returns all occurrences representing a date-time value checked by the datatype <em>xsd:dateTime</em> before a specific date. The date can be defined by a single string literal or as a set of integer values representing the year, month, day and optional the hour, the minute and the second.</p></div>
<h4 id="_dates_in_range_function">3.10.7. Dates-In-Range Function</h4>
<div class="tableblock">
<table rules="all"
width="50%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="25%" />
<col width="75%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>item-identifier</strong></p></td>
<td align="left" valign="top"><p class="table"><a href="http://psi.topicmaps.org/tmql/1.0/functions/dates-in-range">http://psi.topicmaps.org/tmql/1.0/functions/dates-in-range</a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-in-range ( l : string , u : string ) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-in-range ( y1 : integer , m1 : integer , d1 : integer , y2 : integer , m2 : integer , d2 : integer  ) return tuple-sequence</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table"><strong>profile</strong></p></td>
<td align="left" valign="top"><p class="table">fn:dates-in-range ( y1 : integer , m1 : integer , d1 : integer , h1 : integer , min1 : integer , s1 : integer , y2 : integer , m2 : integer , d2 : integer , h2 : integer , min2 : integer , s2 : integer  ) return tuple-sequence</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>The function <em>dates-in-range</em> returns all occurrences representing a date-time value checked by the datatype <em>xsd:dateTime</em> between two specific dates. The dates can be defined by a single string literal or as a set of integer values representing the year, month, day and optional the hour, the minute and the second.</p></div>
<h3 id="_rtm_tmql_integration">3.11. RTM-TMQL integration</h3><div style="clear:left"></div>
<div class="paragraph"><p>Ruby Topic Maps (RTM) is a Topic Maps engine for Ruby which allows querying using TMQL using the RTM-TMQL extension. To do so, Ruby Topic Maps must be run using <a href="http://jruby.org">JRuby</a> which runs on the <a href="http://java.com">JVM</a> and allows using Java libraries like TMQL4J.</p></div>
<h4 id="_installation">3.11.1. Installation</h4>
<div class="paragraph"><p><a href="http://rubygems.org/gems/rtm-tmql">RTM-TMQL</a> is available through RubyGems, the official Ruby package management system. Assuming JRuby installed and configured it can be installed using</p></div>
<div class="literalblock">
<div class="title">Installing RTM-TMQL</div>
<div class="content">
<pre><tt>gem install rtm-tmql</tt></pre>
</div></div>
<div class="paragraph"><p>If there are multiple versions of Ruby installed on the system, the JRuby version is usually available as <tt>jgem</tt>. Alternatively it can be called from JRuby using the parameter <tt>-S</tt>. If JRuby was installed with as administrator, also the gem must be installed as administrator using <tt>sudo</tt>.</p></div>
<div class="literalblock">
<div class="title">Alternatives for Installation</div>
<div class="content">
<pre><tt>jgem install rtm-tmql
jruby -S gem install rtm-tmql
sudo jgem install rtm-tmql
sudo jruby -S gem install rtm-tmql</tt></pre>
</div></div>
<div class="paragraph"><p>The above command installs RTM-TMQL and all its dependencies. RTM-TMQL includes TMQL4J, so there is no need to install it manually. To query something, also a Topic Maps engine is needed. In the following we assume RTM-Ontopia but others should work, too. RTM-Ontopia can be installed the same way as RTM-TMQL:</p></div>
<div class="literalblock">
<div class="title">Installing RTM-Ontopia</div>
<div class="content">
<pre><tt>gem install rtm-ontopia</tt></pre>
</div></div>
<h4 id="_loading">3.11.2. Loading</h4>
<div class="paragraph"><p>To be used in an application, RTM-TMQL has to be loaded. As usual in Ruby this is done using the <tt>require</tt> statement. RTM-TMQL was installed via RubyGems which is consequently needed to find the library. As said above, we will use RTM-Ontopia in the example, so we will load it, too.</p></div>
<div class="literalblock">
<div class="title">Loading RTM-TMQL</div>
<div class="content">
<pre><tt>require 'rubygems'
require 'rtm/tmql'
require 'rtm/ontopia'</tt></pre>
</div></div>
<h4 id="_usage">3.11.3. Usage</h4>
<div class="paragraph"><p>To address common usage, RTM prepares one TMQL engine per topic map automatically. Once loaded, TMQL queries can be run using the <tt>tmql</tt> method:</p></div>
<div class="literalblock">
<div class="title">Running a TMQL query</div>
<div class="content">
<pre><tt>topic_map.tmql("the query")</tt></pre>
</div></div>
<div class="paragraph"><p>The above example assumes a topic map is already available in the variable <tt>topic_map</tt>. The following example shows the creation of such a topic map using a default in-memory connection. Within a Topic Maps engine, each topic map must have a base address which is an IRI according to <a href="http://www.ietf.org/rfc/rfc3987.txt">RFC3987</a>. The topic map contains the letters <em>a</em> to <em>z</em>; each is an instance of <em>letter</em>. The identifier is also used as the default name in this example.</p></div>
<div class="literalblock">
<div class="title">Creating a simple topic map, the letter-map</div>
<div class="content">
<pre><tt>connection = RTM.connect
letter_map = connection.create "http://example.org/my_tm"
letter_type = letter_map.get!("letter")
('a'..'z').each do |letter|
   topic = letter_map.get!(letter)
   letter_type.add_instance(topic)
   topic["-"] = letter
 end</tt></pre>
</div></div>
<div class="paragraph"><p>Now that we have a map, we can run a query for all instances of the topic <em>letter</em>. Within a single call <tt>tmql</tt>, the query is run and the results are returned.</p></div>
<div class="literalblock">
<div class="title">Querying all letters from the letter-map</div>
<div class="content">
<pre><tt>letter_map.tmql("%prefix lm http://example.org/my_tm // lm:letter")</tt></pre>
</div></div>
<div class="paragraph"><p>When first needed, the TMQL runtime is initialized automatically. It is available from the topic map using the <tt>tmql_engine</tt> method. Using the engine object, the TMQL4J properties can be modified. Currently there are two properties available: The topics of the meta model, like the generic tm:name topic can be materialized into the topic map. The following example shows how to enable this setting:</p></div>
<div class="literalblock">
<div class="title">Setting TMQL properties: Materialize Meta Model</div>
<div class="content">
<pre><tt>topic_map.tmql_engine.enable_materialize_meta_model(true)</tt></pre>
</div></div>
<div class="paragraph"><p>For restricted environments it may be useful to disable updates, so the topic map can only be queried but not modified:</p></div>
<div class="literalblock">
<div class="title">Setting TMQL properties: Disable Updates.</div>
<div class="content">
<pre><tt>topic_map.tmql_engine.enable_updates(false)</tt></pre>
</div></div>
<div class="paragraph"><p>Once new properties become available and are not yet implemented in RTM-TMQL, the TMQL4J-internal properties object can be accessed using the <tt>properties</tt> method from the TMQL engine. The following example shows how to disable updates if the direct setter was not available:</p></div>
<div class="literalblock">
<div class="title">Setting TMQL properties: Disable Updates; directly in TMQL4J</div>
<div class="content">
<pre><tt>topic_map.tmql_engine.properties.enableLanguageExtensionTmqlUl(false)</tt></pre>
</div></div>
<div class="paragraph"><p>The same is true for the TMQLRuntime, which is available using the <tt>runtime</tt> method. If there is anything to changed with the runtime or a method to be called directly, it can be accessed using this method.</p></div>
<div class="paragraph"><p>Concluding, RTM-TMQL is just a very thin wrapper layer around TMQL4J which makes calls to the library easier and is closely integrated with RTM.</p></div>
</div>
<h2 id="_tutorials">4. Tutorials</h2>
<div class="sectionbody">
<div class="paragraph"><p>This chapter contains a set of tutorials to learn the topic maps query language and its extensions step by step. To get a fine grasp the session starts with simple examples and get more complicated step by step. Please note that all tutorials are base on the previous one. The explanation of the examples used from previous tutorials will be reduced as much as possible.</p></div>
<div class="paragraph"><p>To create a consitent understanding we use the known topic map about italian operas. Each tutorial will be organzied into three parts. At first we define our use case containing the goals we try to gain with the query. At section two we create the query step by step and get explanations why we make use of this language patterns. In Addition to that alternatives will be shown because of the fact, that there isn&#8217;t the only one solution for our use case. The last section we be a short summary about the new information described by the tutorial.</p></div>
<h3 id="_tutorial_getting_a_topic">4.1. Tutorial: Getting a topic</h3><div style="clear:left"></div>
<h5 id="_use_case">Use Case</h5>
<div class="paragraph"><p>We try to get the topic of the topic map representing the composer Puccini.</p></div>
<h5 id="_solution">Solution</h5>
<div class="paragraph"><p>In relation to the topic maps data model we know, that a topic can be identified by a subject-locator, subject-identifier or item-identifier. In the context of a TMQL query this identifiers can be used as item references to identify a topic map construct.</p></div>
<div class="paragraph"><p>Because of that the first we need a identifier of the topic representing the composer Puccini like <em>http://psi.ontopedia.net/Puccini</em> and the identifier type. We know that the IRI is a subject-identifier of the topic Puccini.</p></div>
<div class="paragraph"><p>The next question we have to answer is the type of expression we have to use to gain our use case. Because of the fact the query is quite simple, we decide to use the path expression style.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      htpp://psi.ontopedia.net/Puccini</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The query is quite short, because it only contains the item reference of the wanted topic item Puccini.</p></div>
</div></div>
<div class="paragraph"><p>In relation to the identifier type, we also can use one of the <em>indicators</em> axis to get a topic by the string-represented IRI if the IRI is used as subject-identifier.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      "http://psi.ontopedia.net/Puccini" &lt;&lt; indicators</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Strings are represented by using double quotes as we see at the beginning of the query. Starting at the literal node of the abstract topic map we can use the <em>indicators</em> axis in backward direction to get the topic using this IRI as subject-identifier.</p></div>
</div></div>
<div class="paragraph"><p>If the IRI is of type subject-locator or item-identifier the using query is similar to the last one except the name of the used axis.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      "http://psi.ontopedia.net/Puccini" &lt;&lt; item</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Returns the topic item using the string literal <em>http://psi.ontopedia.net/Puccini</em> as item-identifier.</p></div>
</div></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      "http://psi.ontopedia.net/Puccini" &lt;&lt; locators</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Returns the topic item using the string literal <em>http://psi.ontopedia.net/Puccini</em> as subject-locator.</p></div>
</div></div>
<h5 id="_summary">Summary</h5>
<div class="paragraph"><p>We learn that a topic can represented by a item reference as a part of the query. In addition to that we also can use the string-literal of the IRI as start node of the navigation over the identifier axes ( <em>indicators</em>, <em>locators</em> or <em>item</em> ) in relation to the identifier type.</p></div>
<h3 id="_tutorial_using_prefixes">4.2. Tutorial: Using Prefixes</h3><div style="clear:left"></div>
<h5 id="_use_case_2">Use Case</h5>
<div class="paragraph"><p>In addition to repeating IRI parts, we want to use prefixes instead of absolute IRIs. We also want to extract the topic item representing the composer Puccini.</p></div>
<h5 id="_solution_2">Solution</h5>
<div class="paragraph"><p>Each TMQL query can start with an environment clause containing prefix definitions and ontology definitions. A prefix definition can be used to define a QName for a absolute IRI used as prefix in the query itselfs.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http:/psi.ontopedia.net/ psi:Puccini</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The keyword <em>%prefix</em> symbolize a prefix definition as a part of the query. Each prefix definition contains three tokens - the keyword <em>prefix</em>, the QName identifier ( <em>psi</em> ) and the absolute IRI <em>http://psi.ontopedia.net</em> ). The remaining part of the query extract the topic item representing Puccini using an item reference as relative IRI using the defined prefix. Like the IRI specification the QName and the remaining IRI part are devided by a colon.</p></div>
</div></div>
<div class="paragraph"><p>In relation to the last tutorial it is not possible to use QNames as parts of string literals. Following query will return an empty result.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http:/psi.ontopedia.net/ "psi:Puccini" &lt;&lt; indicators</tt></pre>
</div></div>
<h5 id="_summary_2">Summary</h5>
<div class="paragraph"><p>The short tutorial show how to use prefixes as a part of the query. Each prefix definition contains three tokens - the keyword <em>prefix</em>, the QName identifier ( <em>psi</em> ) and the absolute IRI <em>http://psi.ontopedia.net</em> ).</p></div>
<h3 id="_tutorial_getting_a_sequence_of_all_characteristics">4.3. Tutorial: Getting a sequence of all characteristics</h3><div style="clear:left"></div>
<h5 id="_use_case_3">Use Case</h5>
<div class="paragraph"><p>In the next iteration we try to extract all characteristics of the topic item Puccini.</p></div>
<h5 id="_solution_3">Solution</h5>
<div class="paragraph"><p>In contrast to the topic maps data model TMQL does not differ between names and occurrences of a topic item. The current draft combines names and occurrences to the characteristics of a topic item. In relation to this there is only one defined axis to get all characteristics of a topic item as one tuple sequence.</p></div>
<div class="paragraph"><p>The first step is to get the topic item we wanted to know. After that we extract the charcteristics using the navigation axis <em>characteristics</em> of the TMQL draft.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>As first part of the query we define a prefix using to reduce the absolute IRIs of the remaining query part to relative IRIs. After that we use the item reference <em>psi:Puccini</em> to identify the topic item Puccini. Using the navigation axis <em>characteristics</em> we navigate from the node representing the topic to all nodes representing characteristics of the topic node. The query does not returns the literals representing the values of the characteristics. It will return a tuple sequence of topic map items representing the characteristics.</p></div>
</div></div>
<div class="paragraph"><p>Because of the fact we want to query the literals representing the values of characteristics, we have to add a new navigation step at the end of the last query. The current draft supports a new navigation axis <em>atomify</em> to serialze a characteristics construct and locators to its literals, mostly strings.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics &gt;&gt; atomify</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>In addition to the last query the forward navigation using the <em>atomify</em> axis extract all values of each characteristic of the topic item Puccini. The query will return a set of string literals representing the values of the characteristics.</p></div>
</div></div>
<div class="paragraph"><p>The <em>characteristics</em> axis supports a optional type representing the topic type of the characteristics construct. The optional type is specified by a topic item reference after the axis name.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics psi:date_of_birth &gt;&gt; atomify</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>In addition to the last query the result of this query only contains all literals of the characteristics of type psi:date_of_birth.</p></div>
</div></div>
<div class="paragraph"><p>In most use case the literals of characteritics are used instead of the characteristics constructs itself. Because of that the non-canonical level contains a term-substitution for the both navigation steps <em>&gt;&gt; characteristics &gt;&gt; atomify</em>. It is possible to use the <em>/</em> followed by the optional type. Please note that the shortcut restricts the optional type, if it is missing a grammar error will be raised.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini / psi:date_of_birth</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>This query has the same result as the last one.</p></div>
</div></div>
<h5 id="_summary_3">Summary</h5>
<div class="paragraph"><p>The tutorial explain how to extract characteristics or their literals using a TMQL query. It explain the functionality of the <em>characteristics</em> and <em>atomify</em> axis with optional type parameters. It also show a non-canonical shortcut for the combination of this both axis.</p></div>
<h3 id="_tutorial_get_names_and_occurrences">4.4. Tutorial:  Get names and occurrences</h3><div style="clear:left"></div>
<h5 id="_use_case_4">Use Case</h5>
<div class="paragraph"><p>The goal is to extract all names and occurrences of the topic Puccini.</p></div>
<h5 id="_solution_4">Solution</h5>
<div class="paragraph"><p>In relation to the last tutorial we use the <em>characteristics</em> axis, too. To extract names as characteristics of a topic item, the optional type shall be used. According to the topic maps data model all names are of type <em>topic-name-type</em>. The current draft of TMQL reserve a identifier representing all names or occurrence as optional parameter of the characteristics axis. The allocated identifier are <em>tm:name</em> and <em>tm:occurrence</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:name
2:
3:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:occurrence</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The query in line 1 returns all names of the topic item representing the composer Puccini. The query make use of the reserved type identifier <em>tm:name</em> as optional argument of the <em>characteristics</em> navigation axis. In line 3 we see the same query except the optional type definition. The query returns all occurrences of the topic item Puccini using the type identifier <em>tm:occurrence</em></p></div>
</div></div>
<h5 id="_summary_4">Summary</h5>
<div class="paragraph"><p>The tutorial explain how to use the optional type argument in addition to the reserved identifier <em>tm:name</em> and <em>tm:occurrence</em> to extract all names or all occurrences of a topic item.</p></div>
<h3 id="_tutorial_getting_all_associations_played_by_a_topic">4.5. Tutorial: Getting all associations played by a topic</h3><div style="clear:left"></div>
<h5 id="_use_case_5">Use Case</h5>
<div class="paragraph"><p>In this case we want to extract all associations played by a the topic item Puccini.</p></div>
<h5 id="_solution_5">Solution</h5>
<div class="paragraph"><p>The extract all associations played by a topic the current draft contains a navigation axis with the identifier <em>players</em>. In forward direction this axis only supports assiciation items and results in a set of topics playing in this association. In backward direction we will get all association items played by the current node, which has to be a topic.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &lt;&lt; players</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The pattern <em>&lt;&lt;</em> symbolize the backward navigation using the navigation axis <em>players</em>. The result of the query will be a set of association items, if the topic plays any role.</p></div>
</div></div>
<h5 id="_summary_5">Summary</h5>
<div class="paragraph"><p>The short tutorial explain how to use the <em>players</em> axis to get all associations played by a topic item.</p></div>
<h3 id="_tutorial_getting_all_instances_of_a_topic_type">4.6. Tutorial: Getting all instances of a topic type</h3><div style="clear:left"></div>
<h5 id="_use_case_6">Use Case</h5>
<div class="paragraph"><p>At this step we want to extract all instance of the topic type Composer.</p></div>
<h5 id="_solution_6">Solution</h5>
<div class="paragraph"><p>The topic type representing a composer has to identify by a item reference too. In addition to that we has to use the <em>types</em> axis in backward direction to get all instances of the given type.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Composer &lt;&lt; types</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The topic type will be addressed by the identifier <em>psi:Composer</em>. By using the <em>types</em> axis in backward direction, we will extract all instances of the given type. The axis will interpret transitive.</p></div>
</div></div>
<div class="paragraph"><p>In addition to the <em>types</em> axis the non-canonical level contains an <em>instances</em> axis which can be used reverse to the <em>types</em> axis.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Composer &gt;&gt; instances</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The result will be the same like the last query.</p></div>
</div></div>
<div class="paragraph"><p>If the usage of the <em>types</em> or <em>instances</em> axis represent the start node of the whole navigation there is another shortcut similar to XPath.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ // psi:Composer</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The result will be the same like the last query. Please note that the shortcut <em>//</em> is only allowed at the beginning of a navigation.</p></div>
</div></div>
<h5 id="_summary_6">Summary</h5>
<div class="paragraph"><p>The tutorial shows how to extract all instances of a given topic type using three different patterns or solutions. We can use the navigation axis <em>types</em> in backward direction and the <em>instances</em> axis in forward direction. In addition to that we can use the shortcut <em>//</em> at the beginning of a query.</p></div>
<h3 id="_tutorial_using_a_type_filter">4.7. Tutorial: Using a type filter</h3><div style="clear:left"></div>
<h5 id="_use_case_7">Use Case</h5>
<div class="paragraph"><p>The next use case is to extract all occurrences of the specific type <em>psi:date_of_birth</em> without using the optional type argument.</p></div>
<h5 id="_solution_7">Solution</h5>
<div class="paragraph"><p>In addition to the optional type argument of navigation axes a path expression supports a filter expression at the end. A filter expression can contain a type filter to remove all elements which are not an instance of the defined type. The filter can only used at the end of the whole navigation and is only applicable for typed constructs or topic items.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics [ . &gt;&gt; types == psi:date_of_birth ]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>A filter definition is always encapsulate by square brackets. To extract the type of the current characteristics object the <em>types</em> axis is used. The current characteristics will be identified by the single dot <em>.</em> similar to the XPath notation. The navigation result will be compared with the given topic type <em>psi:date_of_birth</em>. If the navigation result contains at least the topic type with the identifier <em>psi:date_of_birth</em> the filter will return true and the current characteristics construct will be added to the result set.</p></div>
</div></div>
<div class="paragraph"><p>In addition the current draft specifies a shortcut as non-canonical production for type filters. A type filter can also be identified using the pattern <em>^</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics [ ^ psi:date_of_birth ]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The result will be the same like the last query.</p></div>
</div></div>
<h5 id="_summary_7">Summary</h5>
<div class="paragraph"><p>The tutorial explain how to use a type filter as a part of a path-expression. It explain that the dot <em>.</em> can use to identify the current node of navigation results. The operator <em>==</em> is used to compare to sequences and will return true if at least every element of the second sequence is contained by the first one.</p></div>
<div class="paragraph"><p>In addition the tutorial shows the shortcut for the type filter <em>^</em>.</p></div>
<h3 id="_tutorial_using_an_index_filter">4.8. Tutorial: Using an index filter</h3><div style="clear:left"></div>
<h5 id="_use_case_8">Use Case</h5>
<div class="paragraph"><p>The next step is to extract only the first name of the topic item representing the composer Puccini.</p></div>
<h5 id="_solution_8">Solution</h5>
<div class="paragraph"><p>Another filter type are index filters returning only a subset of the tuple sequence defined by interger literals. An index can be defined as single interger, than the result will only contains the element at the specific index if it exists, otherwise the result will be empty.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:name [ 0 ]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The index filter <em>[ 0 ]</em> specifies the selection of the first element of the navigation results. If puccini has names, the first one will be returned. Please note that topic map constructs are unsorted everytime, so the result of the query can be differ for serveral executions.</p></div>
</div></div>
<div class="paragraph"><p>In addition there is another index filter specify an index range. The result of a query using a range filter will contain all elements between the given indexes. The lower index will be included by the result set.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:name [ 0 .. 1 ]</tt></pre>
</div></div>

<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The index filter <em>[ 0 .. 1 ]</em> specifies the selection of all elements between the index 0 and the index 1. Because of the fact that the first index is included, the result will be the same, like the last query. Please note that topic map constructs are unsorted everytime, so the result of the query can be differ for serveral executions.</p></div>
</div></div>
<div class="paragraph"><p>The shown filter definitions are non-canonical shortcuts for complex expression representing an index filter at the canonical level. The following snippet shows the corresponding canonical expression of the index filters.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:name [ $# == 0 ]
2:
3:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:name [ 0 &lt;= $# AND $# &lt; 1]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Both queries has the same results like the non-canonical one. The variable <em>$</em> represents the current index during the iteration over the navigation result. In line 1 the filter expression contains the condition that the value of the variable <em>$</em> has to be the same like <em>0</em>. In line 3 the value of this variable has to be greater or equal than <em>0</em> and less than <em>1</em>.</p></div>
</div></div>
<h5 id="_summary_8">Summary</h5>
<div class="paragraph"><p>There are two types of index filters ( a simple index filter and a range filter ). Index filter return a subset of the origin results specified by the index bounds. For index ranges the upper bound will be excluded and the lower bound will be included. At the canonical level the variable <em>$#</em> represents the current index of the tuple.</p></div>
<h3 id="_tutorial_using_a_scope_filter">4.9. Tutorial: Using a scope filter</h3><div style="clear:left"></div>
<h5 id="_use_case_9">Use Case</h5>
<div class="paragraph"><p>Extract all names of the topic item representing the composer puccini scoped by the theme <em>psi:short_name</em>.</p></div>
<h5 id="_solution_9">Solution</h5>
<div class="paragraph"><p>There are another filter type representing scope filters. A scope filter defines a theme represented by a topic item reference which has to be contained by themes of the scoped construct.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:name [ . &gt;&gt; scope == psi:short_name ]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The filter will be defined between the square brackets. The dot <em>.</em> symbolize the current node in the context of the abstract topic maps graph. By using the <em>scope</em> axis we extract all themes of the scoped construct. At last we define that the themes has to contain at least the topic item identified by the topic with the reference <em>psi:shot_name</em>.</p></div>
</div></div>
<div class="paragraph"><p>There are a shortcut at the non-canonical grammar level replacing the grammar pattern <em>. &gt;&gt; scope == ' with the symbol '@</em>. In addition the square brackets can be removed.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:name @ psi:short_name</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The query has the same result than the last one.</p></div>
</div></div>
<h5 id="_summary_9">Summary</h5>
<div class="paragraph"><p>Scoping filters can be used to filter the navigation results by a defined topic theme. There are a canonical filter definition based on the <em>scope</em> axis to get all themes of the current node and also a non-canonical shortcut <em>@</em> representing the same statement.</p></div>
<h3 id="_tutorial_using_a_boolean_filter">4.10. Tutorial: Using a boolean filter</h3><div style="clear:left"></div>
<h5 id="_use_case_10">Use Case</h5>
<div class="paragraph"><p>Extract all occurrence of puccini scoped by the theme <em>psi:Web</em> and all names.</p></div>
<h5 id="_solution_10">Solution</h5>
<div class="paragraph"><p>At first we has to analyze the use case. We has to extract all occurrences scoped by the theme <em>Web</em> in namespace <em>psi</em>. To realize that we can use the scoped filter and the optional type of the <em>characteristics</em> axis.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:occurrence @ psi:Web</tt></pre>
</div></div>
<div class="paragraph"><p>The second challenge is to extract all names of the topic item Puccini without any other restrictions.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics tm:name</tt></pre>
</div></div>
<div class="paragraph"><p>The problem is to combine both expression to one complex query according two our principle to extract all by one query. We can not combine the optional types of the navigation axis <em>tm:name</em> and <em>tm:occurrence</em> because of there different type hierarchy, because of that we have to replace the optional type by a type filter.</p></div>
<div class="paragraph"><p>Shortcuts can not be combined with other filter expression, so we have to use the canonical syntax of the scope filter instead of <em>@</em>.</p></div>
<div class="paragraph"><p>Our new filter has to combine different restriction using conjunctions and disjunctions.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      psi:Puccini &gt;&gt; characteristics [ . &gt;&gt; types == tm:name OR ( . &gt;&gt; types == tm:occurrence AND . &gt; scope == psi:Web ) ]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The filter shown by the example code is more complex than the other one, but it returns the values we want. The first part of the filter <em>. &gt;&gt; types == tm:name</em> matches to all names of the topic item Puccini. The second part of out filter <em>( . &gt;&gt; types == tm:occurrence AND . &gt; scope == psi:Web )</em> returns all scoped occurrences with the theme <em>psi:Web</em>. Both expressions are combined as a disjunction symbolized by the keyword <em>OR</em>. Because of the fact that all elements which does not matches to the first filter part has to be occurrences, that filter expression <em>. &gt;&gt; types == tm:occurrence</em> always return true and can be removed.</p></div>
</div></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics [ . &gt;&gt; types == tm:name OR . &gt; scope == psi:Web ]</tt></pre>
</div></div>
<h5 id="_summary_10">Summary</h5>
<div class="paragraph"><p>Filter can be more complex than simply a index filter. They can contain any boolean condition but not non-canonical shortcuts. Sometimes it can be important to check if the boolean expression can be reduced to speed up the execution of the query.</p></div>
<h3 id="_tutorial_using_projections">4.11. Tutorial: Using projections</h3><div style="clear:left"></div>
<h5 id="_use_case_11">Use Case</h5>
<div class="paragraph"><p>In the previous examples we only get simple results as a sequence of singleton tuples. Now we want to extract a tuple sequence containing tripples of a topic item which is a composer, its names and all associations played.</p></div>
<h5 id="_solution_11">Solution</h5>
<div class="paragraph"><p>A navigation always results in a sequence of singleton tuples containing the result of a navigation step from the source node to the target node like names, occurrences or something else. Sometimes we want to fetch informations starting from the same source node but navigates over different axis. To realise that the current draft contains a tuple projection expression. A projection is used to project a current node to a set of target nodes using navigations too. A projection always creates a tuple sequence containing one tuple item for each projection.</p></div>
<div class="paragraph"><p>At first we want to extract the topic items representing an instance of Composer, which we realize with the following query.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ // psi:Composer</tt></pre>
</div></div>
<div class="paragraph"><p>The second tuples shall contain all names of the composers instance, which can be realize by the following query.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ // psi:Composer / tm:name</tt></pre>
</div></div>
<div class="paragraph"><p>As last tuple item, we need all associations played by the composer instance.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ // psi:Composer &lt;&lt; players</tt></pre>
</div></div>
<div class="paragraph"><p>To use a projection we have to extract a navigation part which is similar for all expression we need to combine. In our example the navigation part <em>// psi:Composer</em> is similar for all three queries and can be used as projection base.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ // psi:Composer ( . , . / tm:name , . &lt;&lt; players )</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Projections defined by using round brackets <em>(</em> and <em>)</em>. The round brackets containing a comma separated list of projections. In this case the first projection represents the current node by using the dot <em>.</em>. The second projection projects the current node to its name literals and the last one projects the topic map construct to its played associations.</p></div>
</div></div>
<div class="paragraph"><p>Please note that all projections contained by the projection list uses the same context, which means that the current node will not be inherit by privious projections. The context of the current node will defined by the navigation expression in front of the projection definition. The number of projections is not restricted by the current draft.</p></div>
<div class="paragraph"><p>In relation to the topic maps data model ( TMDM ) each topic map will be unordered. This can be a problem, because the results of queries can be differs and some applications want to extract informations in a defined sequence. To realize the goal, the projection supports a kind of ordering which can be defined by the user as a part of the query. Each tuple of the projection sequence can be ordered in different ways. The interpretation will be start at the first projection and if two elements of the projection are equal the next projection will be used to order and so far. Please note that the tuples will be ordered only if at least on projection contains an ordering keyword <em>ASC</em> and <em>DESC</em>. Both keywords are similar for other languages too and has not to be explained. In addtion, if a keyword is missing, the default keyword <em>ASC</em> will be add if it is necessary.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini ( . ASC , . / tm:name )
2:
3:      =&gt; {    [ Puccini, "Giacomo Puccini" ],
4:                      [ Puccini, "Puccini" ],
5:                      [ Puccini, "Puccini, Giacomo" ] }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The projection definition contains the keyword <em>ASC</em> as part of the first projection. Because of the fact that all values of this projection are equal, the order of the second will be used. The default order is <em>ASC</em>.</p></div>
</div></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini ( . ASC , . / tm:name DESC)
2:
3:      =&gt; {    [ Puccini, "Puccini, Giacomo" ],
4:                      [ Puccini, "Puccini" ],
5:                      [ Puccini, "Giacomo Puccini" ] }</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The projection definition contains the keyword <em>ASC</em> as part of the first projection. Because of the fact that all values of this projection are equal, the order of the second will be used defined by the keyword <em>DESC</em>.</p></div>
</div></div>
<h5 id="_summary_11">Summary</h5>
<div class="paragraph"><p>The tutorial explain the syntax and usage of projections as one possibility to create are non-singleton result tuple. Projections are always encapsulated by round brackets and contains at least one projection tuple. The current node used in projections is always bound to the same value in all projection tuples contained by this projection.</p></div>
<div class="paragraph"><p>In the last examples we learn how to sort the results using the tuple ordering keywords <em>ASC</em> and <em>DESC</em>. If at least one tuple will be ordered by a given keyword, all other will be sort ascending too.</p></div>
<h3 id="_section_select_expressions">4.12. Section: Select expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>In the previous tutorials we only use the path expression style of the TMQL query. Sometimes our use case become to complex to handle it with this expression type and we have to use one of the other types <em>SELECT</em> or <em>FLWR</em>.</p></div>
<h4 id="_tutorial_how_to_use_the_select_style">4.12.1. Tutorial: How to use the select style</h4>
<h5 id="_use_case_12">Use Case</h5>
<div class="paragraph"><p>First we try to get all composer using the select style.</p></div>
<h5 id="_solution_12">Solution</h5>
<div class="paragraph"><p>In remembrance of a previous tutorial we look at the following query realizing our use case, but make use of the path expression style.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ // psi:Composer</tt></pre>
</div></div>
<div class="paragraph"><p>Now we want to use a select expression to realize the same use case. The results should be equal for both queries. At first we take a look to the grammar rule of the select expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      SELECT &lt; value-expression &gt;
2:              WHERE boolean-expression
3:              ORDER BY &lt; value-expression &gt;
4:              UNIQUE
5:              LIMIT interger
6:              OFFSET interger</tt></pre>
</div></div>
<div class="paragraph"><p>For our example we only need a select clause and a boolean expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composer
3:              WHERE $composer ISA psi:Composer</tt></pre>
</div></div>
<div class="paragraph"><p>The first line only defines a simple prefix which we use in line 3. The where-clause starting with the keyword <em>WHERE</em> contains a boolean condition which will be check for each value or item which can be bound to the variable. In line 3 we see the boolean condition <em>$composer ISA psi:Composer</em>.</p></div>
<div class="paragraph"><p>The keyword <em>ISA</em> represents a type restriction for the left-hand arguments. The left-hand argument <em>$composer</em> will bind to each topic exists in the topic map and the binding will be check if it is an instance of the right-hand argument <em>psi:Composer</em>. The result of this condition will be a set of topic items of the type Composer.</p></div>
<div class="paragraph"><p>After the validation of the boolean-expression, each binding will be interpret by the select clause ( <em>SELECT</em> keyword ). In line 2 the select clause only adds the binding of the variable <em>$composer</em> to the tuple sequence representing the result of this query.</p></div>
<div class="paragraph"><p>The overall result will contain exactly all instances of the type composer.</p></div>
<h5 id="_summary_12">Summary</h5>
<div class="paragraph"><p>We learn how to use the select expressions and how to use variables in the context of such expressions. A variable will be bind to each possible value of the topic map and will be validated by the condition contained in the boolean expression. The overall result of valid variables bindings will be passed through the select clause and will be transformed or projected to the results the user want. The select clause can contains more than one value expression similar to the projection of path expressions and can use filters too.</p></div>
<h4 id="_tutorial_ordering_results">4.12.2. Tutorial: Ordering results</h4>
<h5 id="_use_case_13">Use Case</h5>
<div class="paragraph"><p>Now we want to order the results of the last tutorial by there first name.</p></div>
<h5 id="_solution_13">Solution</h5>
<div class="paragraph"><p>To realize this task we make use of the tuple ordering syntax of the path expression. A tuple expression can be ordered by using the keywords <em>ASC</em> and <em>DESC</em>. Similar to tuple expressions a selection expressions containes an order-by clause symbolized by the keywords <em>ORDER BY</em>. The order-by clause can contain a set of value expressions separated by a simple comma and the keyword <em>ASC</em> can be left out.</p></div>
<div class="paragraph"><p>To order our results we need a short path expression describing the values we used for ordering our result tuples.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $composer &gt;&gt; characteristics tm:name &gt;&gt; atomify [ 0 ]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Our task is to order the composers by their first name. A composer instance is bound to the variable <em>$composer</em>. The name of the composer can be extracted by using the navigation <em>&gt;&gt; characteristics tm:name &gt;&gt; atomify</em>. Because there are a set of names contained by a topic item, we use the filter <em>[ 0 ]</em> to get the first one.</p></div>
</div></div>
<div class="paragraph"><p>Now we know the expression to get the first name of a composer. We still have to add the expressions as a part of the order-by clause to our previous select-expression to realize our current use case.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composer
3:              WHERE $composer ISA psi:Composer
4:              ORDER BY $composer &gt;&gt; characteristics tm:name &gt;&gt; atomify [ 0 ]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>In line 4 we see the order by clause containing our short navigation getting the first name of a composer.</p></div>
</div></div>
<h5 id="_summary_13">Summary</h5>
<div class="paragraph"><p>Currently we take use of the order-by clause to order the variable bindings which are valid to the boolean condition. The overall result will be ordered by the given expression. The order-by clause can contain more than one expression to order a result sequence. The second ordering expression will be used if at least two values of the first will be equal.</p></div>
<h4 id="_tutorial_getting_values_of_specific_index_range">4.12.3. Tutorial: Getting values of specific index range</h4>
<h5 id="_use_case_14">Use Case</h5>
<div class="paragraph"><p>We want to realize a simple website displaying all composers by their name. Because of the hugh number of composers we want to implement a paging algorithm, which should be based on TMQL queries. We need a query to extract only the values for the next page between 10 and 20.</p></div>
<h5 id="_solution_14">Solution</h5>
<div class="paragraph"><p>Based on the last query, we have to make two changes. At first we have to extract only the names of the composer instances. The second step is to add a limit and an offset clause to get only the values between the index 10 and 20.</p></div>
<div class="paragraph"><p>To extract the names we can use the navigation axis <em>characteristics</em> and <em>atomify</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $composer &gt;&gt; characteristics tm:name &gt;&gt; atomify [ 0 ]</tt></pre>
</div></div>
<div class="paragraph"><p>The next step is to add simple a selection range to get all tuples between the index 10 and 20.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composer &gt;&gt; characteristics tm:name &gt;&gt; atomify [ 0 ]
3:              WHERE $composer ISA psi:Composer
4:              ORDER BY $composer &gt;&gt; characteristics tm:name &gt;&gt; atomify [ 0 ]
5:              OFFSET  10
6:              LIMIT 10</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The shown syntax is similar to SQL. In line 2 we add the navigation to our select clause to get only the name literals of a composer and not the topic itselfs. To realize the selection range we add a offset-clause with the keyword <em>OFFSET</em> in line 5. The interger value after the keyword represents the first index to select. The limit clause with the keyword <em>LIMIT</em> defines a number of elements which should be selected at most.</p></div>
</div></div>
<h5 id="_summary_14">Summary</h5>
<div class="paragraph"><p>The keyword <em>OFFSET</em> defines an offset-clause which can be used to extract the tuples starting at a specific index, given as literal after the keyword. To extract only a specific number of elements the limit-clause can be used. The limit-clause is defined by the keyword <em>LIMIT</em> and contains a simple interger literal two. If the number of avaible elements is smaller than the limit expect, the result will be smaller than the limit value.</p></div>
<h4 id="_tutorial_use_disjunction">4.12.4. Tutorial: Use disjunction</h4>
<h5 id="_use_case_15">Use Case</h5>
<div class="paragraph"><p>Extract all operas and all composers as one result set.</p></div>
<h5 id="_solution_15">Solution</h5>
<div class="paragraph"><p>In this use case we have to bind the variable to instances of different types, so we have to use a disjunction in combination with two instance-of expressions.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composerOrOpera
3:              WHERE
4:                              $composerOrOpera ISA psi:Composer
5:                      OR
6:                              $composerOrOpera ISA psi:Opera</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The where-clause contains two instance-of expressions in line 4 and 6. The expression in line 4 checks if the variable is bind to a topic item of the type composer and the expression in line 6 checks if it is bound to an instance of opera. By using the keyword <em>OR</em> we define a disjunction which means that at least on of this expression has to satisfy our condition. The interpreter finishes after the first satisfied expression.</p></div>
</div></div>
<h5 id="_summary_15">Summary</h5>
<div class="paragraph"><p>The keyword <em>OR</em> defines a disjunction and the runtime will be finished with iteration step if at least one expression will be satisfied. In reverse the keyword <em>AND</em> symbolize a conjunction of boolean expression.</p></div>
<h4 id="_tutorial_quantified_expression">4.12.5. Tutorial: Quantified Expression</h4>
<h5 id="_use_case_16">Use Case</h5>
<div class="paragraph"><p>The next task is more complex than the other one. We try to extract only composers who has composed at least 10 operas.</p></div>
<h5 id="_solution_16">Solution</h5>
<div class="paragraph"><p>Now we want to extract only a subset of composers. The subset is defined by a new restriction, that the composer has composed at least 10 operas.</p></div>
<div class="paragraph"><p>The semantic pattern <em>at least</em> suggest us, that this is a quantified restriction. The restriction isn&#8217;t unquantified in that meaning that the existing of a fact satisfies the condition. The satisfaction is bind to a numerical bound, which suggests a quantified expression. Quantified expressions are realized as exists-clause in TMQL. A exists clause can be un-quantified like the <em>ISA</em> keyword or can be quantified which we need here. The syntax of a quantified expression is similar to human speach: "at least some satisfies something". The production of a quantified expressions looks like the following one</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      AT LEAST &lt; number &gt; &lt; binding-set &gt; SATISFIES &lt; boolean-expression &gt;</tt></pre>
</div></div>
<div class="paragraph"><p>The next step is to get the informations missing in the production rule. The <em>number</em> will be 10. The boolean expression has to check the restriction of composing an opera. This is modelled as an association in the topic map of the type <em>psi:composed_by</em>. The roles are <em>psi:Composer</em> for the composer and <em>psi:Work</em> for the opera or something else. The condition will look like <em>psi:composed_by ( psi:Work : $opera , psi:Composer : $composer )</em>. The boolean condition dependent on two variables <em>$composer</em> and <em>$opera</em>. The first variable <em>$composer</em> will be bound by the <em>ISA</em> statement of our last query. To bind the variable <em>opera</em> we will use a binding set as we see in the given production.</p></div>
<div class="paragraph"><p>A bindings set is defined as a variable in the context of a sequence of possible values. In our example the variable <em>$opera</em> as an instance of all operas. The production rule of a binding set looks like the following one</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      &lt; variable &gt; IN &lt; context &gt;</tt></pre>
</div></div>
<div class="paragraph"><p>Our context will be the navigation pattern results in all instances of the topic type <em>psi:Opera</em>. The final quantified expression looks like this:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      AT LEAST 10 $opera IN // psi:Opera SATISFIES psi:composed_by ( psi:Work : $opera , psi:Composer : $composer )</tt></pre>
</div></div>
<div class="paragraph"><p>After defining the quantified condition, we have to add them to our select expression as a part of the where clause. Because of the fact that the variable <em>$composer</em> has to bound to an instance of a composer and has to satisfy the quantified expression, we make use of boolean conjunctions.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composer &gt;&gt; characteristics tm:name &gt;&gt; atomify [ 0 ]
3:              WHERE
4:                              $composer ISA psi:Composer
5:                      AND
6:                              AT LEAST 10 $opera IN // psi:Opera SATISFIES psi:composed_by ( psi:Work : $opera , psi:Composer : $composer )</tt></pre>
</div></div>
<div class="paragraph"><p>If we change our use case to get all composers composed at most 10 expression, the query is similar the same except the keyword <em>LEAST</em> will be exchanged with the keyword <em>MOST</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composer &gt;&gt; characteristics tm:name &gt;&gt; atomify [ 0 ]
3:              WHERE
4:                              $composer ISA psi:Composer
5:                      AND
6:                              AT MOST 10 $opera IN // psi:Opera SATISFIES psi:composed_by ( psi:Work : $opera , psi:Composer : $composer )</tt></pre>
</div></div>
<h5 id="_summary_16">Summary</h5>
<div class="paragraph"><p>The tutorial explain the syntax and interpretation of quantified expressions. Quantified expression can restrict an upper or lower number of satisfying bindings. A quantfied expression with the keyword <em>AT LEAST</em> creates the restriction with a lower bound. The keyword <em>AT MOST</em> describe the reverse case. In addition if the number of satisfying elements is not important the keyword <em>SOME</em> can also used.</p></div>
<h4 id="_tutorial_use_the_forall_clause">4.12.6. Tutorial: Use the forall clause</h4>
<h5 id="_use_case_17">Use Case</h5>
<div class="paragraph"><p>Getting all operas which only has name items at the scope italian.</p></div>
<h5 id="_solution_17">Solution</h5>
<div class="paragraph"><p>In reverse to the non quantified expression using the keyword <em>SOME</em> we need an expression checks that all variable bindings satisfy our condition. This type of expression is called forall-clause and will be represented by the keyword <em>EVERY</em>. The syntax of the forall clause is similar to the quantified expression except the quantification expression at the beginning of the sub-expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      EVERY &lt; binding-set &gt; SATISFIES boolean-expression</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>As you see there is no numerical restriction at the beginning of the expression, because every binding of the following binding set has to satisfy the condition.</p></div>
</div></div>
<div class="paragraph"><p>As next step we have to define the condition our variable bindings has to satisfy. At first we need all names of all operas in the scope Italian. To get all names of a opera we can use the <em>characteristics</em> axis.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $opera &gt;&gt; characteristics tm:name</tt></pre>
</div></div>
<div class="paragraph"><p>To get the themes of a name element we use the <em>scope</em> axis.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $name &gt;&gt; scope</tt></pre>
</div></div>
<div class="paragraph"><p>Now we have to check if the theme contains the topic with the identifier <em>psi:Italian</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $name &gt;&gt; scope == psi:Italian</tt></pre>
</div></div>
<div class="paragraph"><p>In combination the forall clause look like the following example.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      EVERY $name IN $opera &gt;&gt; characteristics tm:name SATISFIES $name &gt;&gt; scope == psi:Italian</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The binding set <em>$name IN $opera &gt;&gt; characteristics tm:name</em> binds each name item of the topic bind to the variable <em>$opera</em> to the variable <em>$name</em>. Each of this bindings has to satisfy the condition <em>$name &gt;&gt; scope == psi:Italian</em>. The overall result contains all operas which has only name items at the scope Italian.</p></div>
</div></div>
<div class="paragraph"><p>As last step we have to add the forall clause to our select expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composer &gt;&gt; characteristics tm:name &gt;&gt; atomify [ 0 ]
3:              WHERE
4:                              $composer ISA psi:Composer
5:                      AND
6:                              AT MOST 10 $opera IN // psi:Opera
7:                                      SATISFIES
8:                                                      psi:composed_by ( psi:Work : $opera , psi:Composer : $composer )
9:                                              AND
10:                                                     EVERY $name IN $opera &gt;&gt; characteristics tm:name SATISFIES $name &gt;&gt; scope == psi:Italian</tt></pre>
</div></div>
<h5 id="_summary_17">Summary</h5>
<div class="paragraph"><p>The forall clause is the reverse expression of the exists clause an checks if every binding of a subset satisfies a given condition. If not the origin variable binding is invalid. A forall clause starts with the keyword <em>EVERY</em>.</p></div>
<h4 id="_tutorial_unique_results">4.12.7. Tutorial: Unique results</h4>
<h5 id="_use_case_18">Use Case</h5>
<div class="paragraph"><p>Extract all co-players of any composer instance, but each elements only onetimes.</p></div>
<h5 id="_solution_18">Solution</h5>
<div class="paragraph"><p>At first we have to get all co-players of a specific topic item. There are different possibilities to realize this use case with path expression. We can use the <em>players</em> axis two times each direction one times starting in backward direction.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $composer &lt;&lt; players &gt;&gt; players</tt></pre>
</div></div>
<div class="paragraph"><p>The problem of this expression is that the starting node of the navigation is contained by the result set, but we only wants the co-players and not the items itselfs. The solution of our problem is to use the <em>traverse</em> axis retrieving exacatly the co-players of our topic item.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $composer &gt;&gt; traverse</tt></pre>
</div></div>
<div class="paragraph"><p>The overall select expression looks like the following one using the sub query defined by the last example.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composer &gt;&gt; traverse
3:              WHERE $composer ISA psi:Composer</tt></pre>
</div></div>
<div class="paragraph"><p>If we check the result set, we will found multiple instances of the same topic item. The cause of that is the fact that a topic item can be a co-player of different topic items. For example a opera can be composed by two composers. To solve this problem we can add the keyword <em>UNIQUE</em> which realize a reduction of the result set to a unique tuple sequence contains each item only onetimes.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      SELECT $composer &gt;&gt; traverse
3:              WHERE $composer ISA psi:Composer
4:              UNIQUE</tt></pre>
</div></div>
<h5 id="_summary_18">Summary</h5>
<div class="paragraph"><p>Each item can be contained multiple times by the result set because of the strong linkage between the items of a topic map construct. To extract each element only onetime the keyword <em>UNIQUE</em> can be add to the select expression.</p></div>
<h3 id="_section_flwr_expressions">4.13. Section: Flwr expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>The previous examples and tutorials always using the select or path expression style. There is an other expression style defined by the current draft called flwr expression. The flwr expression looks similar to a programming language and is the only expression type to return special result types like CTM or XTM.</p></div>
<h4 id="_tutorial_how_to_use_flwr_expressions">4.13.1. Tutorial: How to use flwr expressions</h4>
<h5 id="_use_case_19">Use Case</h5>
<div class="paragraph"><p>In this case we try to extract all Composers only using the flwr style.</p></div>
<h5 id="_solution_19">Solution</h5>
<div class="paragraph"><p>In relation to the tutorial using select style to realize this use case, we try to use the flwr style to realize the same goals. At first we take a look at the grammar rule of the flwr-style.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      FOR &lt; binding-set &gt;
2:      WHERE boolean-expression
3:      ORDER BY &lt; value-expressenion &gt;
4:      RETURN content</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The flwr style contains any expressions we already known from the select style. In line 2 there is a where clause containing some boolean condition which has been satisfing by all variable bindings of this expression. Where-clause can be used similar to where clauses of select expression. As we see in line 3 there are also an order-by clause contained by the flwr style. The expression works like order-by clauses of a select expression we learned in a previous example. The binding-set contained by the for-clause in line 1 can be used in the same way like the binding sets of quantified expressions.</p></div>
</div></div>
<div class="paragraph"><p>If we want to use the flwr expression style to realize our use case, we need some additional information. At first we need a binding definition to get all composers. We already know that the binding set binds a variable iteratively to each possible value of the defined context. To get all composers we can use the <em>instances</em> axis with the known type <em>psi:Composer</em> and bind that values to a variable called <em>$composer</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      FOR $composer IN // psi:Composer</tt></pre>
</div></div>
<div class="paragraph"><p>The flwr style enforces that the return clause has to be a part of the final query and cannot be left out. The return statement contains a content definition describe how to export the results of the boolean condition and the bindings set after optional ordering. The return clause can contain every possible content definition of different types, like simple tuple sequences or CTM or XTM. In this case we only need to export the results as simple tuple sequences.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      FOR $composer IN // psi:Composer
3:      RETURN $composer</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>In line 3 we add a return clause starting with the keyword <em>RETURN</em> to get the results we need. The return clause only contains the simple sub expression <em>$composer</em> which will be return the values binding to the variable in the current iteration. The overall results will be a tuple sequence only contains singleton tuples with a topic item of the type composer.</p></div>
</div></div>
<h5 id="_summary_19">Summary</h5>
<div class="paragraph"><p>This first short tutorial of the flwr style describes how to use the flwr style similar to the select style. The expression types have conformities in style and make use of the same sub-expression types including the where-clause and the order-by clause. In reverse to the select style, the flwr style does not support the selection of a specific window and can not unify the values using a unique-clause. But the flwr style only supports the variable binding as a core metric, because of that we have not to use an instance-of expression. A flwr-expression can contain an unspecific number of for-clauses to bind a set of variables in one query. The return-clause of a flwr expression is non optional and defines the return values of the expression itselfs.</p></div>
<h4 id="_tutorial_create_a_topic_map_fragment">4.13.2. Tutorial: Create a topic map fragment</h4>
<h5 id="_use_case_20">Use Case</h5>
<div class="paragraph"><p>A client process wants to extract a specific construct of a topic map managed by the server process. In this case we want to extract our topic map fragment using TMQL and the CTM syntax.</p></div>
<h5 id="_solution_20">Solution</h5>
<div class="paragraph"><p>At first we need to know something about the serialization format CTM. CTM is a simple text based serialization specification for topic maps. Each topic map construct will be represented by a specific text block. The benefit of CTM is the human readable syntax. The main drawback is the fact we needs a special parser.</p></div>
<div class="paragraph"><p>To realize the use case we normaly can use each of the three expression types. The problem is that only one of that can export CTM as a core element of the engine itselfs. If we don&#8217;t want to transform the elements to CTM for oneself, we only can use the flwr-expression. The TMQL draft contains a production rule as a subtype of content, creating a CTM literal in combination with a number of variable bindings. Because we know the return clause of flwr expression contains a content expression, we know how to use the new content type as part of our last query.</p></div>
<div class="paragraph"><p>The last think to know is, how the ctm-content looks like. The ctm-fragments used as part of a TMQL query are encapsulated by a triple quote <em>""""</em>. The interpreter will transform each content between this quotes to CTM. If the content contains a sub-query, at first the query will be interpreted and their results will be transformed to CTM itselfs. The overall result will be a set of little CTM fragments representing a fragment of our queried topic map.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      FOR $composer IN // psi:Composer
3:      RETURN """ { $composer } """</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The query looks like the last example except of the last line. In line 3 we change the result type to CTM content using the tripple quotes. The angle brackets <em>{</em> and <em>}</em> symbolize the internal sub-query. All tokens between both brackets are interpreted as TMQL query which can be return any content type. If the results will be topic map constructs, they will be transformed using the CTM syntax. In addition if the constructs representing a name item, a occurrence item or a variant, the parent topic item will be exported. If the item represents an association role, the parent association item will be exported. For more informations please look at the current CTM draft.</p></div>
</div></div>
<h5 id="_summary_20">Summary</h5>
<div class="paragraph"><p>In this lession we learn how to use the flwr style to export content as CTM. Currently only the flwr style supports the result type CTM as a part of the return clause. A CTM content are encapsulated by tripple quotes <em>""""</em> every time. If the content contains qub-queryies ( encapsulted by angle brackets <em>{</em> and <em>}</em> ) the results of the sub-query interpretation will be transformed to CTM.In addition if the constructs representing a name item, a occurrence item or a variant, the parent topic item will be exported. If the item represents an association role, the parent association item will be exported.</p></div>
<h4 id="_tutorial_create_an_xml_document">4.13.3. Tutorial: Create an XML document</h4>
<h5 id="_use_case_21">Use Case</h5>
<div class="paragraph"><p>According to CTM the flwr style supports the transformation to XML too. Using a special content type called XML-content. In this tutorial we want to extract all composers and their operas as the following XML file.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      &lt;xml&gt;
2:              &lt;composer&gt;
3:                      &lt;name&gt;
4:                              &lt;!-- the first name of the composer --&gt;
5:                      &lt;/name&gt;
6:                      &lt;composed&gt;
7:                              &lt;opera&gt;
8:                                      &lt;!-- the first name of the opera --&gt;
9:                              &lt;/opera&gt;
10:                     &lt;/composed&gt;
11:             &lt;/composer&gt;
12:     &lt;/xml&gt;</tt></pre>
</div></div>
<h5 id="_solution_21">Solution</h5>
<div class="paragraph"><p>Because of the iteration over all composers we need an enclosing query creating the root node <em>&lt;xml&gt;</em>. If it is missing all results will be returned as XML fragments and not as one XML.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      RETURN &lt;xml&gt; &lt;/xml&gt;</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The query will return simple an XML fragment containing one empty note <em>&lt;xml&gt;</em>.</p></div>
</div></div>
<div class="paragraph"><p>To include all composer to our XML file we have to use a sub-query, similar to the last tutorial except the return type has to be XML too. To realize sub-queries we have to add angle brackets containing our sub-query.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      RETURN
3:              &lt;xml&gt;
4:                      {
5:                              FOR $composer IN // psi:Composer
6:                              RETURN &lt;composer&gt; &lt;name&gt; { $composer / tm:name [0] } &lt;/name&gt; &lt;/composer&gt;
7:                      }
8:              &lt;/xml&gt;</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Between the line 4 and 7 we add the query of the last tutorial to get all composers. To export XML again we have to use a flwr query too as wee see in line 5 and 6. In line 5 we define a variable binding for each instance of composer and in line 6 we use a sub-query again to extract the first name of the composer using the <em>characteristics</em> and <em>atomify</em> axis represented by the shortcut <em>/</em>.</p></div>
</div></div>
<div class="paragraph"><p>As next step we have to add a second sub-query based on the variable binding for <em>$composer</em> to extract all operas composed by the current composer topic item. If we want to use the variable <em>$composer</em>, we have to embed our query as part of the return clause of the sub-query binding this variable.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      RETURN
3:              &lt;xml&gt;
4:                      {
5:                              FOR $composer IN // psi:Composer
6:                              RETURN &lt;composer&gt;
7:                                                      &lt;name&gt; { $composer / tm:name [0] } &lt;/name&gt;
8:                                                      &lt;composed&gt;
9:                                                              {
10:                                                                     FOR $opera IN // psi:Opera
11:                                                                     WHERE psi:composed_by ( psi:Composer : $composer , psi:Work : $opera )
12:                                                                     RETURN &lt;opera&gt; { $opera / tm:name [0] } &lt;/opera&gt;
13:                                                             }
14:                                                     &lt;/composed&gt;
15:                                             &lt;/composer&gt;
16:                     }
17:             &lt;/xml&gt;</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Between the line 8 and 14 we embed the sub-query to extract all operas composed by the current composer topic item bind to the variable <em>$composer</em>. In line 10 we bind the variable <em>$opera</em> to every instance of the topic type <em>psi:Opera</em> and in line 11 we make use of the predicate invocations to check if there is an association of type <em>psi:composed_by</em> played by the current opera and composer. The result of valid bindings of <em>$opera</em> will be transformed to XML in line 12. By using a subquery too, we extract the first name of the opera to add the opera item to the XML file embeded by the <em>&lt;opera&gt;</em> XML tag. The overall result will be a XML file which looks like the file we want.</p></div>
</div></div>
<h5 id="_summary_21">Summary</h5>
<div class="paragraph"><p>Flwr expression can also return XML content as well. Using XML-content we can extract informations of the topic map and add them to a specific XML structure. Sub-queries can be used similar to CTM-content to extract values bind to a variable by the encapsulating flwr expressions. Each sub-query inherit the bindings of the parent-query. If the result of sub-query is a topic map construct, it will be transformed using XTM, a XML-based serialization format of topic maps.</p></div>
<h3 id="_section_insert_expressions">4.14. Section: Insert expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>An insert expression can be used to add new content to the queried topic map. The insert expression isn&#8217;t currently a part of the TMQL draft and is an extension designed by the topic maps lab with request to get a part of the final standard of TMQL.</p></div>
<div class="paragraph"><p>Please note that the extension will only supported by the engine by using the modification extension plugin. If the extension is located in the java class path, the engine would be able to use them.</p></div>
<h4 id="_tutorial_insert_a_new_topic">4.14.1. Tutorial: Insert a new topic</h4>
<h5 id="_use_case_22">Use Case</h5>
<div class="paragraph"><p>Similar to the rule - <em>keep it simple</em> - we start with the simple use case to add a new topic with the subject identifier <em>http://tmql4j.topicmapslab.de/types/engine/tmql4j</em> representing the engine itselfs as a topic item.</p></div>
<h5 id="_solution_22">Solution</h5>
<div class="paragraph"><p>The insert expression contains two parts an insert-clause and a where-clause. The where-clause can be used to specify a variable binding using as a part of the insert-expression. In our case the where-clause is not necessary. The insert-clause contains a CTM fragment defining the content to add. Currently we don&#8217;t want to explain how to write CTM fragment, please take a look at the current CTM draft to get more information.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      INSERT """ http://tmql4j.topicmapslab.de/types/engine/tmql4j . """</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The insert-expression allways starts with the keyword <em>INSERT</em> followed by the insert-clause defining a CTM fragment encapsulated by the triple quotes <em>""""</em>. The syntax of the CTM fragment is based on the current CTM draft. In our case we define a topic block using the identifier <em>http://tmql4j.topicmapslab.de/types/engine/tmql4j</em> as a subject-identifier. The dot'.' symbolize the end of the topic definition.</p></div>
</div></div>
<h5 id="_summary_22">Summary</h5>
<div class="paragraph"><p>The insert-expression allways starts with the keyword <em>INSERT</em> followed by the insert-clause defining a CTM fragment encapsulated by the triple quotes <em>""""</em>. The syntax of the CTM fragment is based on the current CTM draft. As optional part a insert-expression can contain a where-clause defining conditions used to bind variables. Variables can be used in the context of the insert-clause, which we will see in a later example.</p></div>
<h4 id="_tutorial_using_variables_as_part_of_the_insert_clause">4.14.2. Tutorial: Using variables as part of the insert-clause</h4>
<h5 id="_use_case_23">Use Case</h5>
<div class="paragraph"><p>In this case we try to add a new association <em>can-queried</em> played by each composer instance and the topic representing the tmql4j engine, we added in the last tutorial.</p></div>
<h5 id="_solution_23">Solution</h5>
<div class="paragraph"><p>We know, that the insert-expression can contain a where-clause to bind variables to specific values. A variable can be used in the context of a CTM fragment contained by the insert-clause to expand the informations of a topic map item which is already contained by the current topic map. Of course we can realize the example whitout using a where-clause if we know all composer instances and their identifier, but this will be more complex than using variables.</p></div>
<div class="paragraph"><p>At first we have to create a where condition binding a variable <em>$composer</em> to each instance of <em>http://psi.ontopedia.net/Composer</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $composer ISA http://psi.ontopedia.net/Composer</tt></pre>
</div></div>
<div class="paragraph"><p>Or we use a prefix definition</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ $composer ISA psi:Composer</tt></pre>
</div></div>
<div class="paragraph"><p>Next we will design a CTM fragment creating a new association item with the type <em>can-queried</em> with two roles. The first role will be of the type <em>topic-content</em> and played by the composer instance. The other role will be played by the tmql4j engine. The role type should be <em>engine</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      can-queried ( topic-content : $composer , engine : http://tmql4j.topicmapslab.de/types/engine/tmql4j )</tt></pre>
</div></div>
<div class="paragraph"><p>To add not the whole topic item as CTM to our CTM fragment we only need to extract one identifier of the topic $composer.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      can-queried ( topic-content : { $composer &gt;&gt; indicators &gt;&gt; atomify [0] } , engine : http://tmql4j.topicmapslab.de/types/engine/tmql4j )</tt></pre>
</div></div>
<div class="paragraph"><p>The last step will be the combination of both elements in our insert-expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      INSERT """ can-queried ( topic-content : { $composer &gt;&gt; indicators &gt;&gt; atomify [0] } , engine : http://tmql4j.topicmapslab.de/types/engine/tmql4j ) """
3:              WHERE $composer ISA psi:Composer</tt></pre>
</div></div>
<div class="paragraph"><p>The engine will create a temporary topic map containing the association item defined by the current insert-expression. All temporary engines will be merged into the origin one to realize the inclusion.</p></div>
<h5 id="_summary_23">Summary</h5>
<div class="paragraph"><p>The where-clause of an insert-expression can be used to add new content to the topic map dependent of some content already contained by the topic map. By binding variables using the where-clause the insert-clause can be used content of the current topic map.</p></div>
<h3 id="_section_delete_expression">4.15. Section: Delete expression</h3><div style="clear:left"></div>
<div class="paragraph"><p>A delete expression can be used to remove existing content of the topic map. The delete expression isn&#8217;t currently a part of the TMQL draft and is an extension designed by the topic maps lab with request to get a part of the final standard of TMQL.</p></div>
<div class="paragraph"><p>Please note that the extension will only supported by the engine by using the modification extension plugin. If the extension is located in the java class path, the engine would be able to use them.</p></div>
<h4 id="_tutorial_remove_a_specific_topic_item">4.15.1. Tutorial: Remove a specific topic item</h4>
<h5 id="_use_case_24">Use Case</h5>
<div class="paragraph"><p>We try to delete a topic item from the topic map. The topic item will be represented by its subject-identifier <em>http://psi.ontopedia.net/Puccini</em>.</p></div>
<h5 id="_solution_24">Solution</h5>
<div class="paragraph"><p>A delete-expression can be splitted into two parts. The where-clause can be used to bind variables or check conditions to extract items to remove. The where-clause is optional and can be left out if the delete-clause is quite simple. The delete-clause define exactly the topic map items to remove.</p></div>
<div class="paragraph"><p>A delete-clause always starts with the keyword <em>DELETE</em> following by the delete-clause and the optional where-clause. The items to remove can addressed by a simple path-expression only contains a topic reference - the subject-identifier.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      DELETE http://psi.ontopedia.net/Puccini</tt></pre>
</div></div>
<div class="paragraph"><p>In context of the opera topic map the execution of this query will be failed, because the topic item with the identifier <em>http://psi.ontopedia.net/Puccini</em> will be used by other topic map constructs for example as reifier or as a association player. A delete-expression only removes independent constructs. Depenedent constructs are topic items used as theme, type or player.</p></div>
<div class="paragraph"><p>The delete-expression supports an optional keyword to remove dependent constructs too. Please take care, because all dependent elements will be removed too. If the delete-expression contains the keyword <em>CASCADE</em> all dependent elements will be removed. This means that all scoped elements, all instances or subtypes and all played associations will be removed from the topic map.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      DELETE CASCADE http://psi.ontopedia.net/Puccini</tt></pre>
</div></div>
<div class="paragraph"><p>All dependencies which can be resolved will be changed too. If a reifier will be removed, the reification will be destroyed but the reified element keep alive.</p></div>
<div class="paragraph"><p>If a topic item will be removed all names, occurrences and played associations deleted. If the topic is a type all instances and subtypes will be removed too. If the topic represents a theme the scoped construct will be removed too, because the semantic of the statement will be changed if the theme is removed.</p></div>
<div class="paragraph"><p>If a name item will be removed, all variants removed too. This process is iterative, which means if a name will be removed because its parent topic was deleted, its variants removed too.</p></div>
<div class="paragraph"><p>If an association item will be removed, all role items will be removed too. This process is iterative, which means if an association will be removed because one of its players are removed, all other roles will be removed too.</p></div>
<h5 id="_summary_24">Summary</h5>
<div class="paragraph"><p>The delete-expression can be split into the delete-clause starting with the keyword <em>DELETE</em> and the optional where-clause. The where-clause can be used to filter the content to remove. The delete expression can contain a navigation to the item to remove, for example a name of a topic. If the keyword <em>CASCADE</em> is missing, the execution fails if the item is dependent to other items. The keyword <em>CASCADE</em> removes all dependencies or the item and its dependencies too. This process is iterative.</p></div>
<h4 id="_tutorial_using_variables_to_remove_content">4.15.2. Tutorial: Using variables to remove content</h4>
<h5 id="_use_case_25">Use Case</h5>
<div class="paragraph"><p>Now we try to remove all names of all instances of composer.</p></div>
<h5 id="_solution_25">Solution</h5>
<div class="paragraph"><p>In this case we will use the where-clause to extract all instances of composer and bind them to the variable <em>$composer</em>. To realize the binding to all instances of composer we use the isa-expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $composer ISA http://psi.ontopedia.net/Composer</tt></pre>
</div></div>
<div class="paragraph"><p>Or we use a prefix definition</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ $composer ISA psi:Composer</tt></pre>
</div></div>
<div class="paragraph"><p>To remove only the names of a composer we have to modify the delete-clause using a navigation-expression getting all name items.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      $composer &gt;&gt; characteristics tm:name</tt></pre>
</div></div>
<div class="paragraph"><p>The last step will be the combination of both query parts to delete all names of all composers.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      DELETE CASCADE composer &gt;&gt; characteristics tm:name
3:              WHERE $composer ISA psi:Composer</tt></pre>
</div></div>
<h5 id="_summary_25">Summary</h5>
<div class="paragraph"><p>By using variables the delete-clause can be used to remove specific elements of a set of topic map constructs like each instance of a specific type. The delete-clause can define simple path-expression to remove a specific item contained by a topic map construct, like its names or identifiers.</p></div>
<h4 id="_tutorial_delete_the_topic_map_content">4.15.3. Tutorial: Delete the topic map content</h4>
<h5 id="_use_case_26">Use Case</h5>
<div class="paragraph"><p>In the last tutorial in this section we want to remove all topic map constructs except the topic map itselfs.</p></div>
<h5 id="_solution_26">Solution</h5>
<div class="paragraph"><p>To realize the removage of all topic map items, the delete-expression can used the special keyword <em>ALL</em>. The keyword <em>CASCADE</em> will be mandatory because the topic map constructs will be depend to each other. The whole delete-expression similar contains only three keywords and nothing more.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      DELETE CASCADE ALL</tt></pre>
</div></div>
<h5 id="_summary_26">Summary</h5>
<div class="paragraph"><p>The special keyword <em>ALL</em> can used to remove the whole content of a topic map.</p></div>
<h3 id="_section_update_expression">4.16. Section: Update expression</h3><div style="clear:left"></div>
<div class="paragraph"><p>An update expression can be used to modify or add content to the queried topic map. The update expression isn&#8217;t currently a part of the TMQL draft and is an extension designed by the topic maps lab with request to get a part of the final standard of TMQL.</p></div>
<h4 id="_tutorial_add_a_new_content_to_a_topic_item">4.16.1. Tutorial: Add a new content to a topic item</h4>
<h5 id="_use_case_27">Use Case</h5>
<div class="paragraph"><p>In this case we want to add a new name to the topic item representing the composer puccini.</p></div>
<h5 id="_solution_27">Solution</h5>
<div class="paragraph"><p>To realize the use case we need to learn something about the update-expressions at first. An update-expression contains a where-clause defining the context of changes. The where-clause contains a simple path-expression to define the items which should be updated. The context of updates is used for all changes defined by the update-clauses and is dependend from the preferred changes.</p></div>
<div class="paragraph"><p>An update-clause similar represented by a triple or a 4-tuple looks like the following one.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      anchor { optional-type } ( SET | ADD ) value-expression</tt></pre>
</div></div>
<div class="paragraph"><p>The <em>anchor</em> defines the kind of changes and has to be an identifier similar to the navigation axis to identify the node or edge of the abstract graph which has to be changed.</p></div>
<div class="paragraph"><p>Because we want to add a new name item, the anchor has to be <em>names</em> representing all changes of name items and we have to use the keyword <em>ADD</em> symbolize the creation of a new name item. The optional type can be left out because our name has no specific type and the default name should be used.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      names ADD "the new name"</tt></pre>
</div></div>
<div class="paragraph"><p>The current context has to be a topic item representing the composer puccini. To get the topic we simply use the subject-identifier of this topic.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1: http://psi.ontopida.net/Puccini</tt></pre>
</div></div>
<div class="paragraph"><p>Or we use a prefix definition</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini</tt></pre>
</div></div>
<div class="paragraph"><p>As final step we have to combine all query snippets to the final update-expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      UPDATE names ADD "the new name"
3:              WHERE psi:Puccini</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>In line 1 we add an evironment-clause containing our prefix definition. Please note that an environment-clause has to add at the beginning of the query everytime. In line 3 we use the where-clause to define the update context and set them to the topic item represented by the subject-identifier <em>psi:Puccini</em>. In line 2 we add our update-clause starting with the keyword <em>UPDATE</em>. The update-expression only contains one update-clause adding a new name with the literal "the new name" to the topic puccini.</p></div>
</div></div>
<h5 id="_summary_27">Summary</h5>
<div class="paragraph"><p>The tutorial explain how to use a update-clause to add a new name to a specific topic item. An update-expression contains at least one update-clause and a where-clause, but the number of update-clauses can be increased if it is necessary. The type of the update context depends on the used anchor. For more information take a look at the previous chapter describing the language specification.</p></div>
<h4 id="_tutorial_change_a_topic_map_construct">4.16.2. Tutorial: Change a topic map construct</h4>
<h5 id="_use_case_28">Use Case</h5>
<div class="paragraph"><p>Now we want to change the value of a occurrence of the same topic item. The occurrence has to be of a website and has to be scoped by the theme Web. The new value has to <em>http://en.wikipedia.org/wiki/Puccini</em> with the correct data type.</p></div>
<h5 id="_solution_28">Solution</h5>
<div class="paragraph"><p>In relation to the last tutorial we need another anchor and another keyword. Currently we want to change the value of an occurrence item of a topic, because of that we have to use the anchor <em>occurrences</em> and the keyword <em>SET</em>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      occurrences SET "http://en.wikipedia.org/wiki/Puccini"</tt></pre>
</div></div>
<div class="paragraph"><p>In our case the literal represent a string value and the data type of the occurrence will be changed to <em>xsd:string</em> automatically if this query will be execute, but our occurrence should represent an IRI. To realize that the data type has to be canged to <em>xsd:anyIRI</em>. To use a specific data type the TMQL draft supports datatyped literals looks like <em>"literal"^^data-type</em>. So we can change our query to the following one.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      occurrences SET "http://en.wikipedia.org/wiki/Puccini"^^xsd:anyIRI</tt></pre>
</div></div>
<div class="paragraph"><p>Because of the fact that the changes will effected the occurrence item itselfs, the current context has to be the occurrence item. To define the context we will use a simple path expression using a scope and type filter to satisfy the requirements of the use case.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/ psi:Puccini &gt;&gt; characteristics psi:website @ psi:Web</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>At first we define the prefix <em>psi</em> representing the absolute IRI <em>http://psi.ontopedia.net/</em>. The rest of the query represent the path expression to get all occurrence of the type website at the scope Web. Our navigation start at the topic item <em>psi:Puccini</em> navigates to the occurrences of the type <em>psi:website</em> using the <em>characteristics</em> axis. The scope filter symbolized by the token <em>@</em> is used to reduce the navigation results to all scoped occurrences.</p></div>
</div></div>
<div class="paragraph"><p>After the combination our final query looks like the following one.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      UPDATE occurrences SET "http://en.wikipedia.org/wiki/Puccini"^^xsd:anyIRI
3:              WHERE psi:Puccini &gt;&gt; characteristics psi:website @ psi:Web</tt></pre>
</div></div>
<h5 id="_summary_28">Summary</h5>
<div class="paragraph"><p>This tutorial explain how to change values of specific topic map constructs at the example of an occurrence item. In addition it also describe how to specify the data-type of a literal used as new value of an occurrence item.</p></div>
<h4 id="_tutorial_combine_update_clauses">4.16.3. Tutorial: Combine update-clauses</h4>
<h5 id="_use_case_29">Use Case</h5>
<div class="paragraph"><p>As I told you before, the update-clause can contain more than one update-clause. Now we combine the last tutorial and adding a new theme <em>updated</em> at the same time.</p></div>
<h5 id="_solution_29">Solution</h5>
<div class="paragraph"><p>At first we look at our last query.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      UPDATE occurrences SET "http://en.wikipedia.org/wiki/Puccini"^^xsd:anyIRI
3:              WHERE psi:Puccini &gt;&gt; characteristics psi:website @ psi:Web</tt></pre>
</div></div>
<div class="paragraph"><p>The next step will be the definition of the new update-clause for add a new theme to the occurrence item. Because of the fact we want to change the scope of the occurrence item, the anchor has to be <em>scope</em> and the keyword <em>ADD</em> because we add a new theme. The theme will be represented as topic reference similar to the topic puccini.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      scope ADD psi:updated</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>Please note that the topic item <em>psi:updated</em> has to exists.</p></div>
</div></div>
<div class="paragraph"><p>In combination our final query looks like this.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      UPDATE occurrences SET "http://en.wikipedia.org/wiki/Puccini"^^xsd:anyIRI , scope ADD psi:updated
3:              WHERE psi:Puccini &gt;&gt; characteristics psi:website @ psi:Web</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>As we see in line 2 both update-clauses simply combined by using a comma.</p></div>
</div></div>
<h3 id="_section_merge_expressions">4.17. Section: Merge expressions</h3><div style="clear:left"></div>
<div class="paragraph"><p>A merge expression can be used to define merge rules which can be used to identify topic items which should be merged. The merge expression isn&#8217;t currently a part of the TMQL draft and is an extension designed by the topic maps lab with request to get a part of the final standard of TMQL.</p></div>
<div class="paragraph"><p>A merge expression contains two different production rules.</p></div>
<div class="paragraph"><p>The first possibility is to use a simple path-expression to define the topics to merge. If the path-expression contains a tuple-expression all tuples of this sequence will be merged. If the path-expression will be represented by a simple-content production, the whole result set will be merged.</p></div>
<div class="paragraph"><p>The second possibility is to use a comma-separated list of value-expressions simply contains variablee which will be bind by the contained where-clause. Each tuple sequence created by the set of value-expression will be merged to one topic.</p></div>
<h4 id="_tutorial_merge_two_specific_topics">4.17.1. Tutorial: Merge two specific topics</h4>
<h5 id="_use_case_30">Use Case</h5>
<div class="paragraph"><p>In this case we try to learn how to use a simple tuple-expression to merge two specific topics. We want to merge the topics with the identifiers <em>http://psi.ontopedia.net/Puccini</em> and <em>http://psi.ontopedia.net/Puccini_2</em>.</p></div>
<h5 id="_solution_30">Solution</h5>
<div class="paragraph"><p>As we can see we will use a tuple-expression to merge the both topics to one new topic according to the merging rules of the topic maps data model. A tuple-expression is a comma-separated list of value-expression encapsulted by round brackets. A value-expression can represent a topic item by using a simple topic reference.</p></div>
<div class="paragraph"><p>A tuple-expression return a tuple sequence containing two topic items looks like the following one.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      ( http://psi.ontopedia.net/Puccini , http://psi.ontopedia.net/Puccini_2 )</tt></pre>
</div></div>
<div class="paragraph"><p>Or we use simple a prefix</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      ( psi:Puccini , psi:Puccini_2 )</tt></pre>
</div></div>
<div class="paragraph"><p>To merge the topics we simply has to add the keyword <em>MERGE</em> in front of our tuple-expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      MERGE ( psi:Puccini , psi:Puccini_2 )</tt></pre>
</div></div>
<h5 id="_summary_29">Summary</h5>
<div class="paragraph"><p>The merge-expression starts with the keyword <em>MERGE</em> followed by a simple path-expression or a set of value-expressions in combination with a where-clause. If the path-expression contains a tuple-expression all elements of each tuple of the generated sequence will be merged to one item.</p></div>
<h4 id="_tutorial_merge_expressions_using_navigation">4.17.2. Tutorial: Merge expressions using navigation</h4>
<h5 id="_use_case_31">Use Case</h5>
<div class="paragraph"><p>Now we want to merge all instances of person with the email address <em>tmql4j@topicmapslab.de</em>.</p></div>
<h5 id="_solution_31">Solution</h5>
<div class="paragraph"><p>In this case we cannot use a tuple-expression because we cannot address the tuples to merge directly. We can use a where-clause or simply a path-expression containing a navigation.</p></div>
<div class="paragraph"><p>At first we try to create a path-expression returning all instances of person, which looks like:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      psi:person &gt;&gt; instances</tt></pre>
</div></div>
<div class="paragraph"><p>The requirement is to extract only persons with the specific email address. We expect that the email is modelled as an occurrence of the type email. To realize our requirement we use a simple filter expression to reduce the set of persons.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      psi:person &gt;&gt; instances [ . &gt;&gt; characteristics psi:email &gt;&gt; atomify == "tmql4j@topicmapslab.de" ]</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>In this example we use a filter expression encapsulated by the square brackets to extract all persons satisfing the given condition. The dot represent one instance of person. Using the <em>characteristics</em> and <em>atomify</em> axes we extract the literal value of the occurrences of the type <em>psi:email</em>. By using the equality operator <em>==</em>, we check if the literal is equal to the given string literal.</p></div>
</div></div>
<div class="paragraph"><p>We simply can use the shortcut for atomifcation of characteristics to reduce the query.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      psi:person &gt;&gt; instances [ . / psi:email == "tmql4j@topicmapslab.de" ]</tt></pre>
</div></div>
<div class="paragraph"><p>To merge the topics we simply has to add the keyword <em>MERGE</em> in front of our path-expression.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      MERGE psi:person &gt;&gt; instances [ . / psi:email == "tmql4j@topicmapslab.de" ]</tt></pre>
</div></div>
<h5 id="_summary_30">Summary</h5>
<div class="paragraph"><p>By using a navigation in combination with filter-expressions the merge-expression can be used to merge topics statisfing a defined condition.</p></div>
<h4 id="_tutorial_complex_merge">4.17.3. Tutorial: Complex merge</h4>
<h5 id="_use_case_32">Use Case</h5>
<div class="paragraph"><p>The last tutorial try to merge persons born in the same city.</p></div>
<h5 id="_solution_32">Solution</h5>
<div class="paragraph"><p>Because of the dependency of the variables we cannot use a path-expression, so we have to use a where-clause to define our merging-rule. The where-clause bind a set of variables, which should be merged. By using a set of value-expressions the user defines which variable should be merged. By using the keyword <em>ALL</em> each variable binding merged to one topic.</p></div>
<div class="paragraph"><p>At first we define out variables bind to two persons and one city. We called them <em>$person</em> , <em>$person</em>'  and <em>$city</em>. The postfixed prime symbolize the query engine, that the variables cannot be bind to the same value. The next will be the definition of the type-instance-relationship of each of this variables. We will use the isa-expression to bind one variable to a set of instances. By using conjunctions we can define the variable binding of each variable.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      $person ISA psi:person
3:      AND
4:      $person' ISA psi:person
5:      AND
6:      $city ISA psi:city</tt></pre>
</div></div>
<div class="paragraph"><p>The next step will be the definition of the born-in association played by the city instance and one of this persons. To realize that we use a predicate-invocation.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      psi:born-in ( psi:person : $person , psi:city : $city )
3:      AND
4:      psi:born-in ( psi:person : $person' , psi:city : $city )</tt></pre>
</div></div>
<div class="paragraph"><p>Now we combine both sub-queries.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      $person ISA psi:person
3:      AND
4:      $person' ISA psi:person
5:      AND
6:      $city ISA psi:city
7:      AND
8:      psi:born-in ( psi:person : $person , psi:city : $city )
9:      AND
10:     psi:born-in ( psi:person : $person' , psi:city : $city )</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>The overall result of this query will be a set of tuples containing one city and two persons which were born in this city.</p></div>
</div></div>
<div class="paragraph"><p>The last step will be to define a list of value-expression to define the items to merge.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>1:      %prefix psi http://psi.ontopedia.net/
2:      MERGE $person , $person'
3:              WHERE
4:                      $person ISA psi:person
5:              AND
6:                      $person' ISA psi:person
7:              AND
8:                      $city ISA psi:city
9:              AND
10:                     psi:born-in ( psi:person : $person , psi:city : $city )
11:             AND
12:                     psi:born-in ( psi:person : $person' , psi:city : $city )</tt></pre>
</div></div>
<div class="exampleblock">
<div class="exampleblock-content">
<div class="paragraph"><p>In line 2 we add the merge-expression using the keyword <em>MERGE</em>. The merge-expression contains a comma-separated list of value-expression defining the set of values to merge. In our case we use the variable <em>$person</em> and <em>$person</em>' which should be merged.</p></div>
</div></div>
<h5 id="_summary_31">Summary</h5>
<div class="paragraph"><p>A merge-expression can contain a complex where-clause defining a merge-rule by using variables and boolean-conditions. In addition to the where-clause the merge-expression contains a comma-separated list of value-expressions used to define a subset of variables to merge to one topic. If the user want to merge all item bound by a variable the keyword <em>ALL</em> can be used as replacement for the comma-separated list of value-expressions.</p></div>
</div>
<h2 id="_additional_material">5. Additional Material</h2>
<div class="sectionbody">
<div class="paragraph"><p>As additional material for learning more about the language TMQL and the described engine TMQL4J we published a set of tutorial slides (in German).</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="7%" />
<col width="71%" />
<col width="21%" />
<tbody>
<tr>
<td align="left" valign="top"><p class="table"><strong>Part No.</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>Content</strong></p></td>
<td align="left" valign="top"><p class="table"><strong>Link</strong></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">1</p></td>
<td align="left" valign="top"><p class="table">Grammar, TMQL Meta Model, Topic Identity, Navigation Concept Part I</p></td>
<td align="left" valign="top"><p class="table"><a href="http://www.topicmapslab.de/articles/tmql-tutorial-part-1"> Link </a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">2</p></td>
<td align="left" valign="top"><p class="table">Navigation Concept Part II, Navigation Concept of the new Draft 2010</p></td>
<td align="left" valign="top"><p class="table"><a href="http://www.topicmapslab.de/articles/tmql-tutorial-part-2"> Link </a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">3</p></td>
<td align="left" valign="top"><p class="table">Filter, Projection, Operators</p></td>
<td align="left" valign="top"><p class="table"><a href="http://www.topicmapslab.de/articles/tmql-tutorial-part-3"> Link </a></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">4</p></td>
<td align="left" valign="top"><p class="table">Functions (Draft 2007, Draft 2010 and TMQL4J Extensions)</p></td>
<td align="left" valign="top"><p class="table">available on 2010-07-09</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">5</p></td>
<td align="left" valign="top"><p class="table">Sorting Within Tuple Sequences, Environment-Clause, Select Style</p></td>
<td align="left" valign="top"><p class="table">available on 2010-07-12</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">6</p></td>
<td align="left" valign="top"><p class="table">FLW(O)R Style, CTM and XTM Fragments</p></td>
<td align="left" valign="top"><p class="table">available on 2010-07-16</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">7</p></td>
<td align="left" valign="top"><p class="table">Conditional Query, TMQL Part II (Insert, Delete and Merge)</p></td>
<td align="left" valign="top"><p class="table">available on 2010-07-19</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">8</p></td>
<td align="left" valign="top"><p class="table">TMQL Part II (Update), Further Work</p></td>
<td align="left" valign="top"><p class="table">available on 2010-07-23</p></td>
</tr>
</tbody>
</table>
</div>
<div>
 <a href="http://www.topicmapslab.de/"><span style="position: fixed; right: 0px; bottom: 50px; display: block; background: url('http://projects.topicmapslab.de/images/sidelabel_right.png') no-repeat scroll; text-indent: 40000px; width: 24px; height: 181px; z-index: 100001;"> topicmapslab.de </span></a>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2010-07-06 16:05:26 Westeuropäische Sommerzeit
</div>
</div>
</body>
</html>
